Overview

A class has one reason to change when every method on it serves a single, coherent concern -- a change to that concern is the ONLY thing that ever forces an edit. Splitting by reason-to-change groups related methods together (a ReportCalculator keeps every pricing method, even if there are several); splitting by "one method per class" would fragment a coherent concern into needlessly many tiny classes with no such organizing principle (Examples 1-2, 57).

An if/elif (or match) chain that must be edited every time a new case is added is the smell -- each new case is a risky edit to code that already worked. The standard fix routes the variation through polymorphism instead: a new subclass, a new registered strategy, or a new handler that plugs into a stable seam without touching the dispatcher (Examples 3-4, 66).

A subtype that "is-a" its base type syntactically (inheritance compiles) but not behaviorally -- typically by narrowing a precondition the base type promised to accept, widening a postcondition the base type promised to satisfy, or raising where the base type promised it would not. Code written against the base type breaks the moment it receives that particular subtype (Examples 5-6, 72).

Every implementer of a fat interface is forced to support (or stub out) methods it has no real implementation for, and a signature change to ANY method on that interface risks breaking every implementer, even ones that never call the changed method. Splitting into role-specific interfaces means each implementer only depends on, and is only affected by changes to, the methods it actually uses (Examples 7-8, 73).

The USUAL direction -- high-level policy depending directly on low-level infrastructure -- is inverted: the high-level policy defines an abstraction (a protocol/interface) it needs, and low-level infrastructure implements that abstraction. The policy depends on the abstraction it owns, never on a concrete infrastructure class (Examples 9-10, 56, 74).

"Which class already has the fields this computation needs?" -- if Order holds the line items, Order is the natural home for order_total(), because computing it anywhere else means first extracting Order's data and duplicating the summing logic outside the class that owns it (Examples 13, 71).

When A aggregates, contains, or closely uses B -- if Order owns its OrderLine objects, Order is the natural place for an add_line() method that constructs a new OrderLine, keeping whatever invariants a new line needs (defaults, validation, wiring to the parent) in one place instead of duplicated at every caller (Examples 14, 71).

A single, stable seam between the UI layer and domain logic -- swapping the UI (web to CLI) or the domain implementation only requires rewiring the controller, since neither side calls the other directly. Without a controller, UI code and domain code become directly coupled, so a change to either risks breaking the other (Examples 15, 71).

An event/callback (the publisher never names or imports the subscriber directly) and an injected abstraction (a class depends on a protocol, not a concrete class, so the concrete implementation can change independently). Composition over inheritance is the same idea applied to class relationships specifically -- a has-a relationship couples less tightly than an is-a one (Examples 17, 26, 58, 71).

Its methods barely touch each other's fields -- they happen to be grouped in the same class without genuinely sharing state or purpose. A low-cohesion class is confusing to navigate (its methods don't tell one coherent story) and resists reuse, because you can rarely take "half" of its behavior without dragging the unrelated rest along (Examples 16, 27, 57, 71).

Adding a new type becomes "add a new class implementing the shared method" instead of "find and edit every type-switch that mentions the old types" -- the type-switch is an OCP violation waiting to happen, since it's easy to miss a branch when a new type is added (Examples 45-46, 71).

Nothing in the business domain of, say, a library or a shop is called a "repository" -- it is a class invented purely to keep persistence logic out of domain classes that would otherwise need to know about databases. A pure fabrication absorbs an infrastructure concern so the domain model stays about the domain, at the cost of one class that doesn't map to anything a domain expert would recognize (Examples 47, 71).

Neither collaborator imports or references the other directly -- both only know the mediator. A change to one collaborator's internals never has to ripple to the other, because the mediator is the only thing that ever names both sides (Examples 48, 71).

Identify the specific point most likely to change (an unstable vendor API, a volatile format), and wrap it behind a stable interface owned by your own code. When the vendor API changes, only the wrapper's implementation changes -- every client of the stable interface is unaffected (Examples 49, 71, 74).

A train wreck is a chained call that reaches through an object to command a third object it happens to hold a reference to (a.get_b().get_c().do_x()) -- it couples the caller to the entire chain of internal structure between it and the final object. "Tell, don't ask" replaces this with a method on the immediate collaborator that does the work internally, so the caller only ever makes one hop (Examples 11-12).

The concrete class being constructed -- a caller asks the factory for "a Shape of this kind" and depends only on the abstract return type, never importing or naming the concrete subclass. Adding a new shape means editing the factory in one place, not every call site that used to construct shapes directly (Examples 18-19, 53, 67, 80).

By making the WHOLE family swap at once -- a single WidgetFactory interface produces a matched button, checkbox, and window that all belong to the same theme, so choosing the factory chooses the entire consistent set. Without it, swapping "which family" means finding and swapping every individual factory-method call site independently, risking a partial, inconsistent swap (Examples 28, 53, 67).

A "telescoping constructor" forces every caller to remember positional parameter order and to pass placeholder values for parts it doesn't need. A builder makes each part self-documenting by name (.with_header(...)) and lets optional parts be included or omitted in any order, readably, with construction logic (validation, defaults) living in one place (Examples 29, 67).

Any test that mutates the singleton's state can leak that mutation into the next test unless something explicitly resets it, and code depending on the singleton cannot easily be tested with a different configuration -- the dependency doesn't show up in any constructor signature, so it's hidden. Dependency injection (co-05) usually replaces it: pass the shared instance in explicitly, and a test can substitute a fresh one with zero global state (Examples 30-31, 65, 67).

Nothing -- neither the client nor the adapted class is modified. The adapter sits between them, translating one interface into the interface the client already expects, which is essential when you don't own one side (a third-party sensor, a legacy API) or don't want to touch code that already has its own tests and callers (Examples 22, 50, 68).

If every COMBINATION of add-ons needs its own subclass (milk, sugar, milk+sugar, ...), the subclass count grows exponentially with the number of independent add-ons. Decorator turns "which combination" into "which decorators did I wrap this in" -- N decorators can be composed in any combination without a single new class per combination, and each decorator adds its behavior around whatever the wrapped object's CURRENT behavior is (Examples 23, 51-52, 68, 79-80).

It centralizes the correct sequencing of calls across several subsystem classes (inventory, payment, shipping) into one entry-point call, so most callers don't need to know or correctly order that sequence themselves. It does NOT hide the subsystem's classes from callers who need finer control -- they can still reach the subsystem classes directly if the facade's default path doesn't fit (Example 24, 68).

A shared method both leaf and composite implement (e.g. size() on both File and Directory) -- the composite's implementation recurses into its children and calls the SAME method on each, so a caller never special-cases "is this a leaf or a group?" at any level of the tree (Examples 34-35, 68, 76).

Virtual proxy defers an expensive operation (loading a large resource) until it's actually accessed; protection proxy checks permission before delegating a call to the real subject; a remote proxy (named but not built here) stands in for an object that lives elsewhere. In every case, the client talks to the proxy exactly as if it were the real subject (Examples 32-33, 68).

Strategy -- because an if/elif chain selecting behavior has to be edited every time a new option appears, while a strategy family lets a new option be added as a new class that plugs into the existing call site untouched. A registry-backed strategy (Example 77) goes further: even a third party can add a strategy with zero edits to core code (Examples 3, 20, 45, 59, 69, 77, 80).

Nothing concrete -- the subject holds a list of subscriber references (or a protocol they satisfy) and never imports a specific subscriber class. Both Observer and Strategy are the same OCP move: Strategy lets you add a new algorithm without editing the call site; Observer lets you add a new subscriber without editing the subject (Examples 21, 44, 55, 69, 75, 80).

Queuing, logging, undoing, and grouping the request with other commands -- a bare function call happens immediately and leaves nothing behind to inspect, replay, or reverse, while a Command object persists as data that other code can act on later (Examples 36-37, 69, 76).

The shared flow (e.g. open, process, close) lives exactly once, in the base class's template method; subclasses override only the step-specific hooks that vary. Without this, every subclass needing a variant of the same overall flow would have to re-implement (and keep in sync) the shared parts too (Examples 25, 54, 69).

Each state object only exposes the methods that are legal FROM that state -- an illegal transition isn't rejected by a conditional check, it simply has no method to call, or the method it does have raises deliberately. A boolean-flag implementation, by contrast, allows any combination of flags to be set, because nothing enumerates which combinations are legal (Examples 38-39, 60, 69).

It hides the collection's internal representation -- a for loop over a custom tree walks it in order without the caller ever seeing the tree's node layout. A lazy iterator additionally avoids doing work (or making a network call) for elements the caller never actually reaches, fetching each page only when asked for the next element (Examples 40-41, 69).

Each case lives in its own handler object, addable to the chain without touching the handlers already there -- a single large handler covering every case would need editing every time a new case appears. Each handler decides independently whether to handle the request or pass it along (Examples 42-43, 69).

Creational (how objects get built: factory method, abstract factory, builder, singleton), structural (how objects are composed: adapter, decorator, facade, composite, proxy), and behavioral (how objects communicate and share responsibility: strategy, observer, command, template method, state, iterator, chain of responsibility). Naming which family a problem belongs to narrows the search for the right tactic quickly (Examples 67-69).

Arriving at it by relieving a real, currently-felt smell, under a test suite pinned BEFORE the refactor and kept green through every step -- not choosing the pattern up front and building toward it in anticipation of a variant that doesn't exist yet. The pinning tests are what make each refactor step verifiably safe (Examples 58-61, 84; the capstone's Step 1-2).

God object (one class doing everything), anemic domain model (data classes with all behavior pulled into a separate service), yo-yo inheritance (understanding a class requires jumping up and down a deep hierarchy), singleton abuse (hidden global coupling), and premature abstraction (a pattern applied for a variant that doesn't exist yet) (Examples 62-66, 78).

The table simply has no entry for it -- there is no code path, however convoluted, that could ever produce that transition, because the lookup itself fails. "Unreached" (as in a boolean-flag model) means the bad combination hasn't happened YET in this particular run, but nothing in the type prevents it from happening in some other run (Examples 81, 84).

A flat FSM needs a distinct state for every COMBINATION of the two concerns (three playback modes times four volume levels needs twelve states), growing multiplicatively as more concerns are added. Hierarchical states let one parent state hold nested substates for one concern, sharing a single parent-level transition across all of them; an orthogonal region lets a second concern (volume) vary completely independently, with no combinatorial states at all (Example 82).

A transition table alone can only say "this event moves to that state" -- it cannot express "only IF some additional condition holds" (a guard adds that condition on top of the table lookup). Entry/exit actions anchor side effects (logging, releasing a lock) to the state BOUNDARY itself, guaranteeing they fire exactly once per crossing, regardless of which event triggered the crossing or how many places in the code could trigger it (Example 83).

This is an OCP violation (co-02) -- route the variation through a Strategy (co-25): give each discount type its own class implementing a shared apply() method, and have checkout() accept whichever strategy it's handed. Adding a new discount becomes "add a new class," never "edit checkout() again" (Examples 3, 59, 70).

This is a DIP violation (co-05) -- CheckoutService should depend on a Repository PROTOCOL, not a concrete database class, injected at construction. Tests substitute a fake, in-memory implementation of the protocol, and the pricing logic can be tested with zero real database involved (Examples 9, 74; the capstone's Step 2).

Model the lifecycle as an explicit finite-state machine (co-35) with a transition table -- a single state: str field replaces the two independent booleans, and the only reachable states are the ones that appear as a VALUE somewhere in the table. "Shipped but not paid" becomes structurally unrepresentable, not merely unlikely (Examples 60, 81, 84).

This calls for hierarchical/orthogonal states (co-36) -- model playback mode as one region (three states) and volume as a completely separate, orthogonal region (four states, independent of playback mode), instead of multiplying them into twelve combined states (Example 82).

This is an ISP violation (co-04) -- split Worker into role-specific protocols (Workable, Eatable), so Robot implements only Workable and structurally cannot be passed anywhere an Eatable is required, catching the mismatch at the type level instead of at a silently-wrong runtime call (Examples 7-8, 73).

This is an LSP violation (co-03) -- Square overriding set_width to also change height breaks the Rectangle contract that width and height vary independently. The fix is usually to stop Square from subclassing Rectangle at all, giving each its own contract, rather than forcing an incompatible is-a relationship (Example 5).

This is a god object (co-34), fixable with SRP (co-01) -- split into EmailValidator, UserRepository, and WelcomeNotifier, each with its own single reason to change and no shared mutable state connecting concerns that have nothing to do with each other (Examples 1-2, 61-62).

This is premature abstraction (co-34) -- a pattern applied for a variant that doesn't exist yet is pure ceremony. Unless a second PaymentStrategy implementation is real or imminent, collapse the indirection back into a plain function or class; reintroduce Strategy only when a genuine second variant shows up (Examples 66, 78).

This is a Decorator (co-21) situation -- three independent add-ons, each its own decorator class wrapping any Notifier, composable in any combination without a subclass per combination. Modeling all eight combinations as subclasses would risk 2^3 = 8 subclasses; three decorators cover every combination by stacking (Examples 51-52).

Add a guard (co-37) -- a boolean condition checked IN ADDITION to the table lookup succeeding. The table says the transition EXISTS; the guard says whether it's ALLOWED to fire right now, given additional state the table alone cannot see (Example 83).

Multiple GRASP seams apply at once: Pure Fabrication (co-12) for the repository (persistence isn't a domain concept), Indirection (co-13)/Low Coupling (co-09) for the notifier (inject a callback or protocol instead of a concrete class), and DIP (co-05) generally -- Library should receive both as constructor parameters, never construct them itself (Example 71).

This is a Protected Variations (co-14) problem -- wrap the volatile vendor API behind a stable interface owned by your own code (e.g. a PricingPort), so a vendor shape change only requires editing the one adapter that implements that port. Every one of the dozen call sites is unaffected (Examples 49, 74).

Root cause: a single class mixed a pure calculation with a notification side effect, so any call to the "read-only-looking" total() method silently mutated shared state. Splitting into ReportCalculator (pure) and ReportMailer (explicit send()) makes the calculation callable any number of times, and sending an email a deliberate, separate action.

Run: python3 kata.py

Output:

30.0
30.0
['emailed total 30.0']

Root cause: two sequential, unrelated if statements each independently mutate the same running total -- when both conditions are true, both fire, stacking the discount. Funneling the decision through ONE selection function (choose_discount) that returns exactly one Strategy object makes "which discount applies" a single decision, structurally preventing two discounts from ever both firing.

Run: python3 kata.py

Output:

90.0

Root cause: Square is-a Rectangle syntactically, but width and height are not independent for a square -- the moment set_width also changes height to preserve "squareness," it breaks the contract Rectangle.set_width promised. Removing the inheritance relationship (rather than forcing Square to fake independence it structurally cannot have) fixes it -- Square becomes its own type with its own contract.

Run: python3 kata.py

Output:

0

Root cause: the fat MultiTool interface forced SimpleScrewdriver to implement saw() even though it has no meaningful implementation, so it stubbed one out that silently returned the wrong result. Splitting into narrow Screwable/Sawable protocols means SimpleScrewdriver never claims to support saw() at all -- isinstance(..., Sawable) correctly reports False, catching the mismatch structurally instead of at a surprising runtime call.

Run: python3 kata.py

Output:

False

Root cause: ReportService constructs its own concrete dependency, so no caller (including a test) can ever hand it something else. Accepting a Repository PROTOCOL as a constructor parameter inverts the dependency: ReportService depends on an abstraction it owns, and any implementation (real or fake) that satisfies that protocol can be injected.

Run: python3 kata.py

Output:

42.0

Root cause: OrderPrinter copied Order's data instead of asking Order to compute the total itself, so the copy went stale the moment Order changed. Information Expert's fix is mechanical: the class that already holds the data (Order) is the natural home for the computation that reads it, so total() always reflects current state by construction.

Run: python3 kata.py

Output:

30.0

Root cause: the caller reached through Customer into Address's internals, coupling itself to the assumption that address is always present. Moving the null-check INTO Customer (which is the class that actually knows whether its own address might be missing) means every caller makes exactly one hop, and the missing-address case is handled once, in the class that owns the data.

Run: python3 kata.py

Output:

unknown

Root cause: EventLog(list) inherits list's ENTIRE interface, including methods that were never meant to be part of an event log's API. Composition (EventLog HOLDS a _events: list[str] instead of BEING one) exposes only record() and iteration -- sort() simply does not exist on the class, so there is no leaked method left to call by accident.

Run: python3 kata.py

Output:

['login', 'purchase', 'logout']

Root cause: three unrelated responsibilities shared one piece of mutable state (self._pending), so an innocuous-looking validation call had a hidden coupling to a LATER, unrelated save. Splitting into three cohesive classes with no shared state removes the coupling entirely -- validator.is_valid() is now a pure function with zero side effects.

Run: python3 kata.py

Output:

[]

Root cause: two independent booleans allow any of the four combinations, including "completed but not assigned," because nothing enumerates which combinations are legal. A transition table with only two entries (open -> assigned via assign, assigned -> completed via complete) has no entry for ("open", "complete"), so the illegal move is rejected by a lookup failure rather than a forgotten if.

Run: python3 kata.py

Output:

event 'complete' is illegal in state 'open'

Root cause: each subclass hardcodes an ABSOLUTE total instead of composing on top of whatever the base class's cost() returns right now, so the hardcoded numbers silently drift the moment the base price changes. A decorator calls self._wrapped.cost() -- the CURRENT value -- and adds its own delta, so a base price change propagates automatically through every decorator stacked on top.

Run: python3 kata.py

Output:

3.75

Root cause: the state transition itself carried no notion of a precondition beyond "this event is recognized" -- it happily fired regardless of whether unlocking was physically possible. A guard checks an ADDITIONAL condition (battery_level > 0) before the state is allowed to change, so the reported state never lies about what actually happened in the real world.

Run: python3 kata.py

Output:

cannot unlock: battery is dead
locked

Every other principle assumes a class already does roughly one thing. LSP is easier to satisfy when a subtype has one clear contract to honor; DIP is easier to apply when the abstraction being extracted covers one coherent responsibility; Strategy and Decorator both wrap or swap ONE behavior cleanly only when that behavior isn't already tangled with two or three others inside the same class. A class that already violates SRP resists every other principle simultaneously.

Because the cost of a pattern (extra indirection, extra classes to navigate) is paid immediately and certainly, while the benefit (flexibility for a future variant) is speculative and may never arrive. Even a CORRECT prediction pays the indirection cost for however long the second variant doesn't yet exist. Refactoring under a pinning test suite, once the smell is real, defers that cost until it's actually justified -- and the tests prove the refactor didn't change behavior along the way.

It's not just that illegal combinations are POSSIBLE -- it's that nothing in the code enumerates which combinations are legal in the first place. A reviewer has to reconstruct the legal state space by reading every method that touches any of the flags; there is no single place that says "these are the only valid combinations." A transition table or a state-object hierarchy makes that enumeration explicit and inspectable.

Strategy swaps ONE algorithm at a time -- it has no notion of "combining" multiple strategies. Decorator is explicitly designed to COMPOSE: each decorator wraps whatever is inside it and adds its own behavior on top, so stacking three decorators applies all three, in any combination, without needing a distinct class per combination. The N independent add-ons stay independent because each is its own decorator, not baked into a subclass alongside the others.

Without a pinning suite, "the refactor didn't change behavior" is an unverified claim -- you're trusting that you read the smelly code correctly and reproduced its exact behavior in the new design. A pinning suite written against the ORIGINAL code, still passing against the REFACTORED code, is direct evidence (not an assertion) that behavior was preserved through every step.

If a Repository PROTOCOL were defined in the infrastructure layer and the domain imported it from there, the domain would still depend (transitively) on the infrastructure package existing at all -- swapping infrastructure would still risk breaking the import. Defining the protocol IN the domain layer, with infrastructure importing IT, means infrastructure can change or be replaced entirely without the domain layer's source ever needing to change, not even an import statement.

SRP tells you to split responsibilities; it doesn't tell you WHERE the split-off responsibility should live if no domain concept naturally owns it. Pure Fabrication names the specific move of inventing a class with no domain meaning (a Repository, a Mediator) purely to hold a responsibility that would otherwise pollute a domain class -- it's the answer to "SRP says split this out, but split it out to WHERE?"

State (co-29) makes illegal moves impossible by NOT giving the wrong methods to the current state object, but the full picture of "what states exist and what moves between them" is scattered across however many state classes there are -- you'd have to read every class to reconstruct the whole machine. A transition table (co-35) is a SINGLE data structure listing every legal (state, event) pair in one place, inspectable and enumerable without reading any class body at all -- useful when you need the whole machine visible at once, e.g. to generate a diagram or audit every legal path.

Every interface has a cost (an extra layer of indirection to read through), so wrapping something that never changes buys nothing and adds navigation overhead for no reason -- that's premature abstraction (co-34) by another name. Protected Variations targets the specific point most LIKELY to change (a vendor API with a history of breaking changes) and accepts direct coupling everywhere else, where the volatility doesn't exist.

"Unreached" is a fact about the runs that have happened SO FAR -- it says nothing about whether some future caller, some new code path, or a bug elsewhere could still produce the illegal combination. "Unrepresentable" is a fact about the TYPE itself -- there is no code path, however contrived, that could ever construct the illegal state, because the representation (a single state string, checked against a table) has no slot for it. The second guarantee holds regardless of what future code does; the first one only holds until something changes.