From 61a3e5c006eed201bd826133174d90d55bee15a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Mon, 20 Apr 2026 11:41:01 +0200 Subject: [PATCH 1/5] feat: add Single Level of Abstraction Principle (SLAP) anchor (#440) Proposed by @eirikbell in #440. Clean-code function-design rule: all statements in a function operate at one abstraction level. Formalises Kent Beck's Composed Method pattern; codified as a function-design rule in Robert C. Martin's Clean Code. Co-Authored-By: Claude Opus 4.7 (1M context) --- ...single-level-of-abstraction-principle.adoc | 50 +++++++++++++++++++ ...gle-level-of-abstraction-principle.de.adoc | 50 +++++++++++++++++++ .../references/catalog.md | 5 ++ 3 files changed, 105 insertions(+) create mode 100644 docs/anchors/single-level-of-abstraction-principle.adoc create mode 100644 docs/anchors/single-level-of-abstraction-principle.de.adoc diff --git a/docs/anchors/single-level-of-abstraction-principle.adoc b/docs/anchors/single-level-of-abstraction-principle.adoc new file mode 100644 index 0000000..4a5f703 --- /dev/null +++ b/docs/anchors/single-level-of-abstraction-principle.adoc @@ -0,0 +1,50 @@ += Single Level of Abstraction Principle (SLAP) +:categories: design-principles +:roles: software-developer, software-architect, educator +:related: cohesion-criteria, kiss-principle, solid-srp, clean-architecture +:proponents: Kent Beck, Robert C. Martin +:tags: clean-code, abstraction, function-design, readability, composed-method +:tier: 2 + +[%collapsible] +==== +Full Name:: Single Level of Abstraction Principle + +Also known as:: SLAP, SLA Principle, One Level of Abstraction Per Function + +[discrete] +== *Core Concepts*: + +Core rule:: +All statements within a single function (or block) should operate at the same level of abstraction. High-level orchestration and low-level mechanics do not belong in the same body. + +Why it works:: +A reader scanning a function can trust it to answer *one* question at *one* resolution. Mixing levels forces the reader to context-switch between "what is this step doing" and "how exactly is it being done" on every line, which is the primary driver of the "I have to read this three times" feeling. + +Applying SLAP:: +* When you notice a function mixing levels, extract the low-level details into well-named helper functions whose names *express the next level of detail*. +* The top-level function becomes a readable summary — almost a table of contents — of the work. +* This is the *Composed Method* pattern (Kent Beck, _Smalltalk Best Practice Patterns_, 1996): build functions from calls to other methods at the same conceptual level. + +Relation to Clean Code:: +Robert C. Martin formalised SLAP as one of the function-design rules in _Clean Code_ (2008), alongside "Functions should be small", "Do one thing", and "Use descriptive names". SLAP is the organising principle that makes "small functions" readable rather than just fragmented. + +Key Proponents:: Kent Beck (_Smalltalk Best Practice Patterns_, 1996 — "Composed Method"), Robert C. Martin (_Clean Code_, 2008). + +[discrete] +== *When to Use*: + +* Refactoring a long function that "does too much" — SLAP tells you *how* to split it, not just that you should +* Code review: a natural smell-detector for functions that mix orchestration with mechanics +* Teaching junior developers a concrete, checkable rule that produces readable code +* Designing a new algorithm top-down: write the high-level steps as calls to not-yet-existing helpers, then fill them in +* Reconstructing the intent of legacy code — lift the orchestration out and the design becomes visible + +[discrete] +== *Related Anchors*: + +* <> - SLAP produces functional cohesion by keeping a function focused on one conceptual step +* <> - SLAP is one concrete technique for keeping functions simple +* <> - SRP applies at the class level what SLAP applies at the function level +* <> - Layered abstraction at the architectural scale mirrors SLAP at the code scale +==== diff --git a/docs/anchors/single-level-of-abstraction-principle.de.adoc b/docs/anchors/single-level-of-abstraction-principle.de.adoc new file mode 100644 index 0000000..ccbabf2 --- /dev/null +++ b/docs/anchors/single-level-of-abstraction-principle.de.adoc @@ -0,0 +1,50 @@ += Single Level of Abstraction Principle (SLAP) +:categories: design-principles +:roles: software-developer, software-architect, educator +:related: cohesion-criteria, kiss-principle, solid-srp, clean-architecture +:proponents: Kent Beck, Robert C. Martin +:tags: clean-code, abstraktion, funktionsdesign, lesbarkeit, composed-method +:tier: 2 + +[%collapsible] +==== +Vollständiger Name:: Single Level of Abstraction Principle + +Auch bekannt als:: SLAP, SLA-Prinzip, ein Abstraktionsniveau pro Funktion + +[discrete] +== *Kernkonzepte*: + +Grundregel:: +Alle Anweisungen innerhalb einer Funktion (oder eines Blocks) sollen auf dem gleichen Abstraktionsniveau liegen. High-Level-Orchestrierung und Low-Level-Mechanik gehören nicht in denselben Rumpf. + +Warum es funktioniert:: +Wer eine Funktion überfliegt, möchte sich darauf verlassen können, dass sie *eine* Frage auf *einer* Auflösung beantwortet. Gemischte Ebenen zwingen den Leser auf jeder Zeile zum Kontextwechsel zwischen "was macht dieser Schritt" und "wie genau wird das gemacht" — genau das erzeugt das "ich muss das dreimal lesen"-Gefühl. + +Anwendung von SLAP:: +* Wenn eine Funktion Ebenen mischt, ziehe die Low-Level-Details in gut benannte Hilfsfunktionen, deren Namen *die nächste Detailstufe ausdrücken*. +* Die Top-Level-Funktion wird zur lesbaren Zusammenfassung — fast einem Inhaltsverzeichnis — der Arbeit. +* Das ist das *Composed Method*-Pattern (Kent Beck, _Smalltalk Best Practice Patterns_, 1996): baue Funktionen aus Aufrufen anderer Methoden auf derselben konzeptuellen Ebene auf. + +Bezug zu Clean Code:: +Robert C. Martin hat SLAP in _Clean Code_ (2008) als eine der Regeln für Funktionsdesign formalisiert, neben "Funktionen sollen klein sein", "Nur eine Sache tun", und "Sprechende Namen verwenden". SLAP ist das ordnende Prinzip, das "kleine Funktionen" lesbar statt fragmentiert macht. + +Schlüsselvertreter:: Kent Beck (_Smalltalk Best Practice Patterns_, 1996 — "Composed Method"), Robert C. Martin (_Clean Code_, 2008). + +[discrete] +== *Wann zu verwenden*: + +* Refactoring einer zu langen Funktion — SLAP sagt dir *wie* du sie zerlegst, nicht nur *dass* du es solltest +* Code Review: natürlicher Smell-Detektor für Funktionen, die Orchestrierung mit Mechanik mischen +* Junior-Entwickler eine konkrete, prüfbare Regel beibringen, die zu lesbarem Code führt +* Top-down ein neues Verfahren entwerfen: die High-Level-Schritte als Aufrufe noch-nicht-existierender Hilfsfunktionen schreiben, dann füllen +* Intent von Legacy-Code rekonstruieren — Orchestrierung herausziehen, dann wird das Design sichtbar + +[discrete] +== *Verwandte Anker*: + +* <> - SLAP erzeugt funktionale Kohäsion, indem es eine Funktion auf einen konzeptuellen Schritt fokussiert +* <> - SLAP ist eine konkrete Technik, Funktionen einfach zu halten +* <> - SRP macht auf Klassenebene, was SLAP auf Funktionsebene macht +* <> - Geschichtete Abstraktion auf Architekturebene spiegelt SLAP auf Codeebene +==== diff --git a/skill/semantic-anchor-translator/references/catalog.md b/skill/semantic-anchor-translator/references/catalog.md index a86ca50..b0ceb81 100644 --- a/skill/semantic-anchor-translator/references/catalog.md +++ b/skill/semantic-anchor-translator/references/catalog.md @@ -229,6 +229,11 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Ron Jeffries, Kent Beck - **Core:** Don't build for hypothetical futures, speculative generality anti-pattern, incremental design, delete dead code +### Single Level of Abstraction Principle (SLAP) +- **Also known as:** SLAP, One Level of Abstraction Per Function +- **Proponents:** Kent Beck, Robert C. Martin +- **Core:** All statements inside a function should live at one abstraction level; mixing orchestration with mechanics is the main driver of unreadable code; refactor by extracting low-level details into named helpers so the outer function reads like a table of contents; formal expression of Beck's Composed Method pattern, codified as a Clean Code function-design rule by Martin + ### GoF Design Patterns - **Also known as:** Design Patterns, Gang of Four Patterns - **Proponents:** Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides From 61c59f25e963c1e44673ce55e1af140fa9002a66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Mon, 20 Apr 2026 11:42:39 +0200 Subject: [PATCH 2/5] feat: add Occam's Razor anchor (#439) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Proposed by @danielschmeiss in #439. Epistemic parsimony principle: among competing hypotheses, prefer the one with fewest assumptions. Distinct from KISS — Occam applies to explanations (debugging, diagnosis, architecture rationale), KISS to solutions. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/anchors/occams-razor.adoc | 55 +++++++++++++++++++ docs/anchors/occams-razor.de.adoc | 55 +++++++++++++++++++ .../references/catalog.md | 5 ++ 3 files changed, 115 insertions(+) create mode 100644 docs/anchors/occams-razor.adoc create mode 100644 docs/anchors/occams-razor.de.adoc diff --git a/docs/anchors/occams-razor.adoc b/docs/anchors/occams-razor.adoc new file mode 100644 index 0000000..1c70f67 --- /dev/null +++ b/docs/anchors/occams-razor.adoc @@ -0,0 +1,55 @@ += Occam's Razor +:categories: problem-solving +:roles: software-architect, software-developer, consultant, educator +:related: kiss-principle, yagni, five-whys, mece, devils-advocate +:proponents: William of Ockham +:tags: heuristic, parsimony, epistemology, simplicity, hypothesis-selection +:tier: 2 + +[%collapsible] +==== +Full Name:: Occam's Razor (also spelled Ockham's Razor) + +Also known as:: Law of Parsimony, Principle of Parsimony, _Lex Parsimoniae_, "Entities should not be multiplied beyond necessity" + +[discrete] +== *Core Concepts*: + +Core rule:: +Among competing hypotheses that explain the same observations equally well, prefer the one that requires the fewest assumptions. The razor *shaves off* unnecessary entities, causes, or mechanisms. + +What it is *not*:: +* Not a rule to be brief or terse — that is a stylistic choice, not an epistemic one. +* Not a proof that the simpler answer is *true* — only a guide to which hypothesis to prefer, investigate first, or commit to under uncertainty. +* Not a licence for KISS-style solution simplification — Occam operates at the level of *explanations*, KISS at the level of *solutions*. They overlap but are not the same razor. + +How it is used:: +* As a *selection filter* under uncertainty — when two stories fit the data, start with the one that assumes less. +* As a *debugging heuristic* — before assuming a bug requires a race condition plus caching layer plus stale DNS, check whether a single off-by-one explains everything. +* In *architecture decisions* — a design that needs three new components to justify itself is evidentially weaker than one that reuses existing pieces. +* In *diagnostic reasoning* — prefer explanations grounded in the system's known mechanics over ones that require novel failure modes. + +Limits and counters:: +The razor is a *prior*, not a verdict. Reality is frequently non-parsimonious, and "simpler" is relative to a chosen ontology. Einstein's corollary — "_as simple as possible, but no simpler_" — warns against under-fitting. Pair Occam with evidence, not as a substitute for it. + +Key Proponents:: William of Ockham (c. 1287–1347, _Summa Logicae_, _Quodlibetal Questions_); the principle predates Ockham in Aristotle and Scotus but carries his name due to his repeated methodological use of it. Modernised by Bertrand Russell and formalised as minimum-description-length / Bayesian simplicity priors in 20th-century philosophy of science. + +[discrete] +== *When to Use*: + +* Debugging: triage competing theories of a bug before instrumenting for all of them +* Architecture review: challenge proposals that introduce new components to explain observed requirements +* Root-cause analysis: pair with Five Whys to avoid stopping at an elaborate but unjustified explanation +* Incident response: the outage likely has *one* cause matching the data, not a conspiracy +* Requirements clarification: pick the interpretation that requires fewest hidden assumptions about the user +* LLM prompting: ask the model to prefer the explanation with the fewest moving parts when diagnosing + +[discrete] +== *Related Anchors*: + +* <> - Sibling razor applied to *solutions* rather than *explanations* +* <> - Applies parsimony to future requirements: don't build what you can't justify +* <> - Occam helps pick which "why" to pursue when the chain forks +* <> - Both disciplines of hypothesis hygiene; MECE ensures coverage, Occam ranks by parsimony +* <> - Devil's Advocate stress-tests the hypothesis Occam has selected +==== diff --git a/docs/anchors/occams-razor.de.adoc b/docs/anchors/occams-razor.de.adoc new file mode 100644 index 0000000..ca4a539 --- /dev/null +++ b/docs/anchors/occams-razor.de.adoc @@ -0,0 +1,55 @@ += Occams Rasiermesser +:categories: problem-solving +:roles: software-architect, software-developer, consultant, educator +:related: kiss-principle, yagni, five-whys, mece, devils-advocate +:proponents: William of Ockham +:tags: heuristik, sparsamkeit, epistemologie, einfachheit, hypothesenauswahl +:tier: 2 + +[%collapsible] +==== +Vollständiger Name:: Occams Rasiermesser (auch Ockhams Rasiermesser) + +Auch bekannt als:: Sparsamkeitsprinzip, Prinzip der Parsimonie, _Lex Parsimoniae_, "Entitäten sind nicht über das Notwendige hinaus zu vermehren" + +[discrete] +== *Kernkonzepte*: + +Grundregel:: +Unter konkurrierenden Hypothesen, die dieselben Beobachtungen gleich gut erklären, bevorzuge diejenige mit den wenigsten Annahmen. Das Rasiermesser *schneidet* unnötige Entitäten, Ursachen oder Mechanismen weg. + +Was es *nicht* ist:: +* Keine Regel, sich kurzzufassen — das wäre stilistisch, nicht erkenntnistheoretisch. +* Kein Beweis, dass die einfachere Antwort *wahr* ist — nur eine Präferenzregel, welche Hypothese zuerst zu untersuchen oder unter Unsicherheit anzunehmen ist. +* Keine Lizenz für KISS-artige Lösungsvereinfachung — Occam arbeitet auf der Ebene der *Erklärungen*, KISS auf der Ebene der *Lösungen*. Sie überlappen, sind aber nicht dasselbe Rasiermesser. + +Wie es angewendet wird:: +* Als *Auswahlfilter* unter Unsicherheit — wenn zwei Geschichten zu den Daten passen, beginne mit der, die weniger annimmt. +* Als *Debugging-Heuristik* — bevor du annimmst, dass ein Bug eine Race Condition plus Caching-Schicht plus veralteten DNS braucht, prüfe, ob ein einzelner Off-by-One alles erklärt. +* Bei *Architekturentscheidungen* — ein Entwurf, der drei neue Komponenten zu seiner Rechtfertigung braucht, steht evidenziell schwächer da als einer, der Bestehendes wiederverwendet. +* Im *diagnostischen Denken* — bevorzuge Erklärungen, die auf den bekannten Mechanismen des Systems basieren, gegenüber solchen, die neue Fehlermodi voraussetzen. + +Grenzen und Gegenargumente:: +Das Rasiermesser ist ein *Prior*, kein Urteil. Die Realität ist häufig nicht sparsam, und "einfacher" ist relativ zur gewählten Ontologie. Einsteins Korollar — "_so einfach wie möglich, aber nicht einfacher_" — warnt vor Underfitting. Paare Occam mit Evidenz, nicht als Ersatz für sie. + +Schlüsselvertreter:: Wilhelm von Ockham (ca. 1287–1347, _Summa Logicae_, _Quodlibeta_); das Prinzip ist älter (Aristoteles, Duns Scotus), trägt aber Ockhams Namen wegen seines konsequenten methodischen Einsatzes. Modernisiert durch Bertrand Russell und in der Wissenschaftsphilosophie des 20. Jh. als Minimum-Description-Length / Bayesianische Simplicity-Priors formalisiert. + +[discrete] +== *Wann zu verwenden*: + +* Debugging: konkurrierende Theorien für einen Bug triagieren, bevor du für alle instrumentierst +* Architektur-Review: Vorschläge hinterfragen, die neue Komponenten einführen, um beobachtete Anforderungen zu erklären +* Root-Cause-Analyse: kombiniert mit Five Whys verhindert Stehenbleiben bei elaborierten, aber unbegründeten Erklärungen +* Incident Response: der Ausfall hat wahrscheinlich *eine* Ursache, die zu den Daten passt, keine Verschwörung +* Requirements-Klärung: wähle die Interpretation, die die wenigsten versteckten Annahmen über den Nutzer macht +* LLM-Prompting: bitte das Modell, bei der Diagnose die Erklärung mit den wenigsten beweglichen Teilen zu bevorzugen + +[discrete] +== *Verwandte Anker*: + +* <> - Verwandtes Rasiermesser, angewandt auf *Lösungen* statt *Erklärungen* +* <> - Überträgt Parsimonie auf zukünftige Anforderungen: baue nicht, was du nicht rechtfertigen kannst +* <> - Occam hilft zu wählen, welchem "Warum" zu folgen ist, wenn die Kette sich verzweigt +* <> - Beide sind Hygienewerkzeuge für Hypothesen; MECE sichert Abdeckung, Occam bewertet nach Sparsamkeit +* <> - Devil's Advocate stresst die von Occam gewählte Hypothese +==== diff --git a/skill/semantic-anchor-translator/references/catalog.md b/skill/semantic-anchor-translator/references/catalog.md index b0ceb81..3986eb2 100644 --- a/skill/semantic-anchor-translator/references/catalog.md +++ b/skill/semantic-anchor-translator/references/catalog.md @@ -357,6 +357,11 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors ### Devil's Advocate - **Core:** Argue against proposal to stress-test it +### Occam's Razor +- **Also known as:** Law of Parsimony, Lex Parsimoniae, Ockham's Razor +- **Proponents:** William of Ockham +- **Core:** Among competing hypotheses that explain the same observations equally well, prefer the one requiring the fewest assumptions; applies to *explanations* (debugging, diagnosis, architecture rationale), distinct from KISS which applies to *solutions*; a selection prior under uncertainty, not a proof of truth; Einstein's corollary "as simple as possible, but no simpler" warns against under-fitting + ### Morphological Box - **Proponents:** Fritz Zwicky - **Core:** Matrix of parameters × options to explore solution space From f55f9732d33de2e754f04b66ca8207c1306eb802 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Mon, 20 Apr 2026 11:43:59 +0200 Subject: [PATCH 3/5] feat: add Code Smells anchor (#435) Proposed by @ma7tz in #435. Surface indications in code that point to deeper design problems; Fowler's *Refactoring* (1999) catalogue as primary source, Kent Beck coined the term, Robert C. Martin's *Clean Code* Appendix A extends the enumeration. Scope broadened from the original "Code Smells according to Martin" framing to give Beck/Fowler canonical attribution. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/anchors/code-smells.adoc | 56 +++++++++++++++++++ docs/anchors/code-smells.de.adoc | 56 +++++++++++++++++++ .../references/catalog.md | 5 ++ 3 files changed, 117 insertions(+) create mode 100644 docs/anchors/code-smells.adoc create mode 100644 docs/anchors/code-smells.de.adoc diff --git a/docs/anchors/code-smells.adoc b/docs/anchors/code-smells.adoc new file mode 100644 index 0000000..d1f5118 --- /dev/null +++ b/docs/anchors/code-smells.adoc @@ -0,0 +1,56 @@ += Code Smells +:categories: design-principles +:roles: software-developer, software-architect, educator, team-lead +:related: fowler-patterns, cohesion-criteria, solid-principles, solid-srp, kiss-principle +:proponents: Kent Beck, Martin Fowler, Robert C. Martin +:tags: refactoring, code-quality, clean-code, maintainability, smells +:tier: 2 + +[%collapsible] +==== +Full Name:: Code Smells + +Also known as:: Bad Smells in Code, Refactoring Smells + +[discrete] +== *Core Concepts*: + +What a smell is:: +A *surface indication* in the code that usually points to a deeper design problem. Smells are heuristic: they are quick to spot, do not prove a defect exists, and are evaluated in context. A smell tells you *where to look*, not *what to do*. + +Fowler's catalogue:: +Martin Fowler's _Refactoring_ (1999, 2nd ed. 2018, with the original smell chapter co-authored by Kent Beck) is the canonical catalogue. Each smell is paired with a refactoring that typically resolves it. Common groupings of Fowler's 20+ smells: ++ +* *Bloaters* — structures that grow too large: Long Method, Large Class, Long Parameter List, Primitive Obsession, Data Clumps. +* *Object-Orientation Abusers* — incomplete or inverted use of OO: Switch Statements, Refused Bequest, Alternative Classes with Different Interfaces, Temporary Field. +* *Change Preventers* — structures that multiply the cost of change: Divergent Change (one class changes for many reasons), Shotgun Surgery (one change touches many classes), Parallel Inheritance Hierarchies. +* *Dispensables* — code that earns its keep poorly: Comments (as compensation), Duplicate Code, Lazy Class, Data Class, Dead Code, Speculative Generality. +* *Couplers* — excessive or inappropriate coupling: Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man. + +Martin's extensions:: +Robert C. Martin's _Clean Code_ (2008), Appendix A "Smells and Heuristics", extends Fowler's catalogue with additional smells organised by concern — Comments, Environment, Functions, General, Java, Names, Tests — about 65 heuristics in total. These are complementary refinements, not a replacement for Fowler's set. + +Terminology origin:: +Kent Beck coined the term "code smell" in the 1990s; Fowler wrote the book that made it the standard vocabulary. "It just feels wrong" became expressible and teachable. + +Key Proponents:: Kent Beck (coined the term), Martin Fowler (_Refactoring_, 1999, 2nd ed. 2018 — canonical catalogue), Robert C. Martin (_Clean Code_, 2008, Appendix A — extended enumeration). + +[discrete] +== *When to Use*: + +* Code review: a shared vocabulary for "this feels wrong" that turns taste into checkable signals +* Refactoring planning: each smell maps to known refactorings, so a smell is an actionable handle +* Teaching: junior developers learn faster from a named smell + named fix than from abstract design lectures +* Technical-debt inventory: enumerate smells to quantify and prioritise cleanup work +* LLM prompting: asking the model to "identify code smells" activates a richer inspection than "find problems" +* Self-review before PR: a mental pass over the smell list catches issues a reader would otherwise flag + +[discrete] +== *Related Anchors*: + +* <> - Same author; Fowler's broader design-pattern vocabulary +* <> - Many smells (Feature Envy, Divergent Change, Large Class) are low-cohesion symptoms +* <> - SOLID violations manifest as identifiable smells; smell→principle is a useful diagnostic direction +* <> - Divergent Change is almost always an SRP violation +* <> - Speculative Generality and Comments-as-compensation are KISS failures +==== diff --git a/docs/anchors/code-smells.de.adoc b/docs/anchors/code-smells.de.adoc new file mode 100644 index 0000000..3a510d6 --- /dev/null +++ b/docs/anchors/code-smells.de.adoc @@ -0,0 +1,56 @@ += Code Smells +:categories: design-principles +:roles: software-developer, software-architect, educator, team-lead +:related: fowler-patterns, cohesion-criteria, solid-principles, solid-srp, kiss-principle +:proponents: Kent Beck, Martin Fowler, Robert C. Martin +:tags: refactoring, code-qualität, clean-code, wartbarkeit, smells +:tier: 2 + +[%collapsible] +==== +Vollständiger Name:: Code Smells + +Auch bekannt als:: Bad Smells in Code, Refactoring-Smells, "schlechter Geruch im Code" + +[discrete] +== *Kernkonzepte*: + +Was ein Smell ist:: +Ein *oberflächliches Indiz* im Code, das üblicherweise auf ein tieferliegendes Designproblem hinweist. Smells sind heuristisch: sie sind schnell zu erkennen, beweisen keinen Defekt und müssen im Kontext bewertet werden. Ein Smell sagt dir *wo du hinschauen sollst*, nicht *was zu tun ist*. + +Fowlers Katalog:: +Martin Fowlers _Refactoring_ (1999, 2. Aufl. 2018, das ursprüngliche Smell-Kapitel zusammen mit Kent Beck) ist der kanonische Katalog. Jeder Smell ist mit einem Refactoring gepaart, das ihn typischerweise auflöst. Übliche Gruppierung der über 20 Fowler-Smells: ++ +* *Bloaters* — zu groß gewachsene Strukturen: Long Method, Large Class, Long Parameter List, Primitive Obsession, Data Clumps. +* *Object-Orientation Abusers* — unvollständige oder verdrehte OO-Nutzung: Switch Statements, Refused Bequest, Alternative Classes with Different Interfaces, Temporary Field. +* *Change Preventers* — Strukturen, die Änderungskosten vervielfachen: Divergent Change (eine Klasse ändert sich aus vielen Gründen), Shotgun Surgery (eine Änderung berührt viele Klassen), Parallel Inheritance Hierarchies. +* *Dispensables* — Code, der seinen Platz schlecht rechtfertigt: Comments (als Kompensation), Duplicate Code, Lazy Class, Data Class, Dead Code, Speculative Generality. +* *Couplers* — übermäßige oder unangemessene Kopplung: Feature Envy, Inappropriate Intimacy, Message Chains, Middle Man. + +Martins Erweiterungen:: +Robert C. Martins _Clean Code_ (2008), Anhang A "Smells and Heuristics", erweitert Fowlers Katalog um weitere Smells, organisiert nach Thema — Comments, Environment, Functions, General, Java, Names, Tests — insgesamt ca. 65 Heuristiken. Das sind komplementäre Verfeinerungen, kein Ersatz für Fowlers Set. + +Herkunft des Begriffs:: +Kent Beck prägte den Begriff "Code Smell" in den 1990ern; Fowler schrieb das Buch, das ihn zum Standardvokabular machte. "Fühlt sich irgendwie falsch an" wurde damit ausdrückbar und lehrbar. + +Schlüsselvertreter:: Kent Beck (Begriffsprägung), Martin Fowler (_Refactoring_, 1999, 2. Aufl. 2018 — kanonischer Katalog), Robert C. Martin (_Clean Code_, 2008, Anhang A — erweiterte Enumeration). + +[discrete] +== *Wann zu verwenden*: + +* Code Review: gemeinsames Vokabular für "das fühlt sich falsch an", das Geschmack in prüfbare Signale verwandelt +* Refactoring-Planung: jeder Smell ist mit bekannten Refactorings verknüpft, also ein handlungsleitender Griff +* Lehre: Junior-Entwickler lernen schneller an benanntem Smell + benanntem Fix als an abstrakten Designvorträgen +* Technical-Debt-Inventur: Smells zählen, um Aufräumarbeit zu quantifizieren und zu priorisieren +* LLM-Prompting: "identifiziere Code Smells" aktiviert eine reichere Inspektion als "finde Probleme" +* Selbst-Review vor PR: ein mentaler Durchgang über die Smell-Liste fängt Issues, die ein Reviewer sonst flagt + +[discrete] +== *Verwandte Anker*: + +* <> - Gleicher Autor; Fowlers breiteres Design-Pattern-Vokabular +* <> - Viele Smells (Feature Envy, Divergent Change, Large Class) sind Symptome niedriger Kohäsion +* <> - SOLID-Verletzungen zeigen sich als erkennbare Smells; Smell→Prinzip ist eine nützliche Diagnoserichtung +* <> - Divergent Change ist fast immer eine SRP-Verletzung +* <> - Speculative Generality und Comments-als-Kompensation sind KISS-Verstöße +==== diff --git a/skill/semantic-anchor-translator/references/catalog.md b/skill/semantic-anchor-translator/references/catalog.md index 3986eb2..4276ab0 100644 --- a/skill/semantic-anchor-translator/references/catalog.md +++ b/skill/semantic-anchor-translator/references/catalog.md @@ -234,6 +234,11 @@ Source: https://github.com/LLM-Coding/Semantic-Anchors - **Proponents:** Kent Beck, Robert C. Martin - **Core:** All statements inside a function should live at one abstraction level; mixing orchestration with mechanics is the main driver of unreadable code; refactor by extracting low-level details into named helpers so the outer function reads like a table of contents; formal expression of Beck's Composed Method pattern, codified as a Clean Code function-design rule by Martin +### Code Smells +- **Also known as:** Bad Smells in Code, Refactoring Smells +- **Proponents:** Kent Beck (coined term), Martin Fowler, Robert C. Martin +- **Core:** Surface indications in code that usually point to deeper design problems; Fowler's *Refactoring* (1999) catalogue groups ~20 smells into Bloaters (Long Method, Large Class, Primitive Obsession), OO Abusers (Switch Statements, Refused Bequest), Change Preventers (Divergent Change, Shotgun Surgery), Dispensables (Duplicate Code, Dead Code, Speculative Generality), Couplers (Feature Envy, Message Chains); Martin's *Clean Code* Appendix A extends with ~65 heuristics across Comments, Functions, Names, Tests; each smell pairs with a canonical refactoring — a smell tells you *where to look*, not *what to do* + ### GoF Design Patterns - **Also known as:** Design Patterns, Gang of Four Patterns - **Proponents:** Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides From 84c2829391fa6d15ebb4a144c0a9becbd6c534bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Mon, 20 Apr 2026 11:44:35 +0200 Subject: [PATCH 4/5] docs: add 2026-04-20 changelog entry for SLAP, Occam's Razor, Code Smells Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/changelog.adoc | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/changelog.adoc b/docs/changelog.adoc index a7c20b8..607d2a4 100644 --- a/docs/changelog.adoc +++ b/docs/changelog.adoc @@ -2,6 +2,14 @@ A chronological record of all semantic anchors added to the catalog. Community contributors are credited with thanks. +== 2026-04-20 + +*New anchors:* + +* *Single Level of Abstraction Principle (SLAP)* — Kent Beck's Composed Method, codified as a Clean Code function-design rule by Robert C. Martin (proposed by https://github.com/eirikbell[@eirikbell] in https://github.com/LLM-Coding/Semantic-Anchors/issues/440[#440]) +* *Occam's Razor* — William of Ockham's parsimony principle applied to explanations, debugging and architecture rationale (proposed by https://github.com/danielschmeiss[@danielschmeiss] in https://github.com/LLM-Coding/Semantic-Anchors/issues/439[#439]) +* *Code Smells* — Kent Beck / Martin Fowler / Robert C. Martin catalogue of surface indications pointing to deeper design problems (proposed by https://github.com/ma7tz[@ma7tz] in https://github.com/LLM-Coding/Semantic-Anchors/issues/435[#435]) + == 2026-04-15 *New anchors* (proposed by Ralf D. Müller in https://github.com/LLM-Coding/Semantic-Anchors/issues/436[#436]): From ff68d81125926f2148f94bcd88f7fe65936b9765 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=7BAI=7Df=20D=2E=20M=C3=BCller?= Date: Mon, 20 Apr 2026 12:06:09 +0200 Subject: [PATCH 5/5] chore: regenerate metadata JSON for SLAP, Occam's Razor, Code Smells Co-Authored-By: Claude Opus 4.7 (1M context) --- website/public/data/anchors.json | 97 +++++++++++++++++++++++++++++ website/public/data/categories.json | 5 +- website/public/data/metadata.json | 10 +-- website/public/data/roles.json | 11 ++++ 4 files changed, 117 insertions(+), 6 deletions(-) diff --git a/website/public/data/anchors.json b/website/public/data/anchors.json index 73649e7..035da78 100644 --- a/website/public/data/anchors.json +++ b/website/public/data/anchors.json @@ -223,6 +223,40 @@ "filePath": "docs/anchors/clean-architecture.adoc", "tier": 3 }, + { + "id": "code-smells", + "title": "Code Smells", + "categories": [ + "design-principles" + ], + "roles": [ + "software-developer", + "software-architect", + "educator", + "team-lead" + ], + "related": [ + "fowler-patterns", + "cohesion-criteria", + "solid-principles", + "solid-srp", + "kiss-principle" + ], + "proponents": [ + "Kent Beck", + "Martin Fowler", + "Robert C. Martin" + ], + "tags": [ + "refactoring", + "code-quality", + "clean-code", + "maintainability", + "smells" + ], + "filePath": "docs/anchors/code-smells.adoc", + "tier": 2 + }, { "id": "cohesion-criteria", "title": "Cohesion Criteria", @@ -2321,6 +2355,38 @@ "filePath": "docs/anchors/nelson-rules.adoc", "tier": 3 }, + { + "id": "occams-razor", + "title": "Occam’s Razor", + "categories": [ + "problem-solving" + ], + "roles": [ + "software-architect", + "software-developer", + "consultant", + "educator" + ], + "related": [ + "kiss-principle", + "yagni", + "five-whys", + "mece", + "devils-advocate" + ], + "proponents": [ + "William of Ockham" + ], + "tags": [ + "heuristic", + "parsimony", + "epistemology", + "simplicity", + "hypothesis-selection" + ], + "filePath": "docs/anchors/occams-razor.adoc", + "tier": 2 + }, { "id": "owasp-top-10", "title": "OWASP Top 10", @@ -2687,6 +2753,37 @@ "filePath": "docs/anchors/semantic-versioning.adoc", "tier": 3 }, + { + "id": "single-level-of-abstraction-principle", + "title": "Single Level of Abstraction Principle (SLAP)", + "categories": [ + "design-principles" + ], + "roles": [ + "software-developer", + "software-architect", + "educator" + ], + "related": [ + "cohesion-criteria", + "kiss-principle", + "solid-srp", + "clean-architecture" + ], + "proponents": [ + "Kent Beck", + "Robert C. Martin" + ], + "tags": [ + "clean-code", + "abstraction", + "function-design", + "readability", + "composed-method" + ], + "filePath": "docs/anchors/single-level-of-abstraction-principle.adoc", + "tier": 2 + }, { "id": "socratic-method", "title": "Socratic Method", diff --git a/website/public/data/categories.json b/website/public/data/categories.json index 5b31fc2..d6e02ea 100644 --- a/website/public/data/categories.json +++ b/website/public/data/categories.json @@ -30,6 +30,7 @@ "id": "design-principles", "name": "Design Principles & Patterns", "anchors": [ + "code-smells", "cohesion-criteria", "crc-cards", "fowler-patterns", @@ -59,6 +60,7 @@ "gof-visitor-pattern", "grasp", "kiss-principle", + "single-level-of-abstraction-principle", "solid-dip", "solid-isp", "solid-lsp", @@ -128,7 +130,8 @@ "devils-advocate", "feynman-technique", "five-whys", - "morphological-box" + "morphological-box", + "occams-razor" ] }, { diff --git a/website/public/data/metadata.json b/website/public/data/metadata.json index 2de3faa..d67dc4d 100644 --- a/website/public/data/metadata.json +++ b/website/public/data/metadata.json @@ -1,15 +1,15 @@ { - "generatedAt": "2026-04-15T09:23:51.831Z", + "generatedAt": "2026-04-20T09:55:32.712Z", "version": "1.0.0", "counts": { - "anchors": 131, + "anchors": 134, "categories": 14, "roles": 13 }, "statistics": { - "averageRolesPerAnchor": "3.15", + "averageRolesPerAnchor": "3.16", "averageCategoriesPerAnchor": "1.01", - "anchorsWithTags": 91, - "anchorsWithRelated": 62 + "anchorsWithTags": 94, + "anchorsWithRelated": 65 } } \ No newline at end of file diff --git a/website/public/data/roles.json b/website/public/data/roles.json index a3be1aa..0a252ef 100644 --- a/website/public/data/roles.json +++ b/website/public/data/roles.json @@ -60,6 +60,7 @@ "moscow", "mvp", "myers-briggs-type-indicator", + "occams-razor", "owasp-top-10", "pert", "plain-english-strunk-white", @@ -120,6 +121,7 @@ "name": "Educator / Trainer", "anchors": [ "4mat", + "code-smells", "cohesion-criteria", "crc-cards", "diataxis-framework", @@ -137,11 +139,13 @@ "lehmans-classification", "mental-model-according-to-naur", "myers-briggs-type-indicator", + "occams-razor", "para-method", "pert", "plain-english-strunk-white", "red-green-tdd", "save-the-cat", + "single-level-of-abstraction-principle", "socratic-method", "solid-principles", "story-circle-dan-harmon", @@ -229,6 +233,7 @@ "atam", "c4-diagrams", "clean-architecture", + "code-smells", "cohesion-criteria", "cqrs", "crc-cards", @@ -277,9 +282,11 @@ "mece", "mikado-method", "morphological-box", + "occams-razor", "owasp-top-10", "pugh-matrix", "regulated-environment", + "single-level-of-abstraction-principle", "solid-dip", "solid-isp", "solid-lsp", @@ -308,6 +315,7 @@ "bem-methodology", "chain-of-thought", "clean-architecture", + "code-smells", "cohesion-criteria", "conventional-commits", "cqrs", @@ -362,6 +370,7 @@ "mikado-method", "morphological-box", "mutation-testing", + "occams-razor", "owasp-top-10", "para-method", "plain-english-strunk-white", @@ -370,6 +379,7 @@ "red-green-tdd", "regulated-environment", "semantic-versioning", + "single-level-of-abstraction-principle", "solid-dip", "solid-isp", "solid-lsp", @@ -407,6 +417,7 @@ "atam", "bluf", "c4-diagrams", + "code-smells", "control-chart-shewhart", "cynefin-framework", "definition-of-done",