/design-patterns

name: design-patterns
description: Use when choosing how to structure code for a recurring problem. Covers the patterns that earn their keep, the ones that usually do not, and how to recognize when a pattern is being applied for its own sake.
metadata:
  category: development
  version: 1.0.0
  tags: [design-patterns, architecture, solid, abstraction]

Design Patterns

Purpose

Apply structural patterns as solutions to problems you actually have. A pattern applied prophylactically is just indirection with a formal name.

When to Use

• A problem recurs and the current structure requires a change in many places each time.
• Choosing between inheritance, composition, and configuration.
• Reviewing code that is heavily abstracted and hard to follow.
• Designing an extension point for third parties.

Capabilities

• Creational: factory, builder, dependency injection.
• Structural: adapter, facade, decorator, proxy.
• Behavioral: strategy, observer, command, state machine.
• Concurrency: producer-consumer, worker pool, circuit breaker.
• Recognizing pattern misuse: the singleton-as-global, the abstract factory of one.

Inputs

• The problem being solved and how often it recurs.
• The axis of expected change — what varies, and what stays fixed.
• Who extends the code: you, your team, or external consumers.

Outputs

• A structure with a named rationale.
• The specific change it makes cheap, stated explicitly.

Workflow

1. **Name the axis of variation.** A pattern buys flexibility along exactly one axis, at the cost of indirection along all of them. If you cannot name the axis, do not apply a pattern. 2. **Count the instances.** One implementation needs no strategy interface. Two might. Three definitely does. 3. **Choose the lightest structure that works.** A function passed as a parameter is a strategy. It does not need a class hierarchy. 4. **Write it concretely first.** Then extract the pattern when the second case arrives — the shape of the abstraction will be obvious rather than guessed. 5. **Justify the indirection.** If a reader must open three files to answer "what happens when I call this", the pattern is costing more than it returns.

Best Practices

• Composition over inheritance, nearly always. Inheritance couples you to the parent's internals forever.
• Strategy, adapter, and decorator earn their keep constantly. Abstract factory and visitor rarely do outside frameworks.
• A singleton is a global variable with better manners. Use dependency injection instead — it makes the dependency visible and the code testable.
• A state machine with explicit states and transitions beats a tangle of boolean flags every time.
• Circuit breakers, retries, and timeouts are patterns too, and they are more likely to save you than any of the Gang of Four.
• Two similar pieces of code are not necessarily duplication. Deduplicating things that merely look alike couples things that change for different reasons.

Examples

**Explicit state machine instead of boolean soup:**

# Before: state is implied by three booleans, and half the combinations are invalid.
if order.is_paid and not order.is_shipped and not order.is_cancelled:
    ship(order)

# After: states are enumerated, transitions are the only way to move.
class OrderState(Enum):
    PENDING = auto()
    PAID = auto()
    SHIPPED = auto()
    CANCELLED = auto()

TRANSITIONS: dict[OrderState, set[OrderState]] = {
    OrderState.PENDING:   {OrderState.PAID, OrderState.CANCELLED},
    OrderState.PAID:      {OrderState.SHIPPED, OrderState.CANCELLED},
    OrderState.SHIPPED:   set(),
    OrderState.CANCELLED: set(),
}

def transition(order: Order, to: OrderState) -> None:
    if to not in TRANSITIONS[order.state]:
        raise InvalidTransition(f"{order.state.name} -> {to.name}")
    order.state = to

Invalid states are now unrepresentable, and the legal transitions are readable in one place.

Notes

• The dependency-inversion principle is about direction, not about interfaces. An interface with exactly one implementation, created only to "follow the principle", inverts nothing.
• Facades are the most under-used pattern in large codebases: a single, small entry point to a subsystem does more for comprehensibility than any amount of internal cleanliness.