kayaman/design-patterns

Design Patterns

Reference: Design Patterns (GoF), Head First Design Patterns (Freeman & Robson), Refactoring to Patterns (Kerievsky)

When to Apply

• Selecting a pattern for a recurring design problem
• Refactoring code that exhibits a known code smell toward a pattern
• Reviewing whether an applied pattern is justified or over-engineered
• Deciding if a language feature (lambdas, protocols, generics) eliminates the need for a pattern
• Communicating design intent using shared pattern vocabulary

---

The Two GoF Maxims

Every pattern decision MUST be guided by these two principles:

1. Program to an interface, not an implementation — depend on abstractions; swap implementations without changing clients
2. Favor object composition over class inheritance — assemble behavior from collaborating objects rather than building class trees

---

Creational Patterns

Select based on what varies in object creation:

| Pattern | Intent | Use When | Avoid When | |---------|--------|----------|------------| | Abstract Factory | Create families of related objects without specifying concrete classes | Multiple product families must be interchangeable (e.g., UI themes, platform adapters) | Only one product family exists | | Builder | Separate construction of complex objects from representation | Object has many optional parameters or multi-step construction | Constructor with 1–3 required params suffices | | Factory Method | Let subclasses decide which class to instantiate | The exact type depends on runtime context or configuration | A simple constructor call is clear enough | | Prototype | Create objects by cloning an existing instance | Creating from scratch is expensive or involves complex setup | Object graphs are simple and cheap to construct | | Singleton | Ensure one instance with global access | Almost never — prefer DI container-managed lifecycle | Testing, concurrency, or coupling matter (most cases) |

• MUST NOT use Singleton in new code — use dependency injection to manage single-instance lifecycle externally
• SHOULD prefer Builder over telescoping constructors when an object has 4+ configuration options
• SHOULD use Factory Method or Abstract Factory when the concrete type is a decision that should be deferred

---

Structural Patterns

Select based on how objects and classes are composed:

| Pattern | Intent | Use When | Avoid When | |---------|--------|----------|------------| | Adapter | Convert an incompatible interface into one clients expect | Integrating third-party code or legacy systems | You control both interfaces and can change one | | Bridge | Decouple abstraction from implementation so both vary independently | Two orthogonal dimensions of variation (e.g., shape × renderer) | Only one dimension varies | | Composite | Treat individual objects and compositions uniformly as a tree | Recursive part-whole hierarchies (file systems, UI components, org charts) | The structure is flat, not tree-shaped | | Decorator | Attach behavior dynamically without subclassing | Adding optional, combinable responsibilities at runtime | Behavior is always required — just put it in the class | | Facade | Simplified interface to a complex subsystem | Clients need a streamlined entry point; subsystem internals should be hidden | The subsystem is already simple | | Flyweight | Share fine-grained objects to save memory | Thousands of similar objects with shared intrinsic state | Object count is small; optimization is premature | | Proxy | Surrogate controlling access (lazy loading, caching, protection, remote) | Access control, expensive initialization, or cross-network access | Direct access has no cost or risk |

• SHOULD use Adapter as the primary pattern for integrating external systems
• SHOULD prefer Decorator over inheritance for optional, combinable behavior
• MUST separate intrinsic (shared) from extrinsic (contextual) state when applying Flyweight

---

Behavioral Patterns

Select based on how objects communicate and assign responsibility:

| Pattern | Intent | Use When | Avoid When | |---------|--------|----------|------------| | Chain of Responsibility | Pass request along a chain until handled | Middleware pipelines, event processing, validation chains | A single handler always processes the request | | Command | Encapsulate a request as an object | Undo/redo, queuing, logging, transaction replay | The action is simple and needs no history | | Interpreter | Define grammar and interpret sentences | Small, domain-specific languages (query filters, rules engines) | The grammar is complex — use a parser generator | | Iterator | Sequential access without exposing internals | Built into virtually all modern languages — rarely implement manually | Language-native iteration exists | | Mediator | Centralize complex inter-object communication | Many objects with complex, many-to-many interactions | Objects have simple, direct relationships | | Memento | Capture and restore state without breaking encapsulation | Undo, snapshots, time-travel debugging | State is trivial to reconstruct | | Observer | Notify dependents when state changes | Event-driven systems, reactive UI, pub-sub | Use framework-native reactive patterns (RxJS, signals, hooks) | | State | Alter behavior when internal state changes | Object behaves differently in distinct states with defined transitions | A simple if/else on one flag suffices | | Strategy | Interchangeable algorithm family | Multiple algorithms for the same task, selected at runtime | In FP languages, just pass a lambda/function | | Template Method | Algorithm skeleton with overridable steps | Fixed workflow with varying steps across subclasses | Composition with Strategy achieves the same without inheritance | | Visitor | Add operations to elements without modifying their classes | New operations are frequent; element types are stable | Element hierarchy changes often — every Visitor breaks |

• SHOULD prefer Strategy over Template Method — composition over inheritance
• SHOULD use language-native constructs (iterators, lambdas, reactive streams) before implementing Iterator, Strategy, or Observer manually
• MUST evaluate whether the pattern adds value beyond what the language provides natively

---

Modern Patterns Beyond GoF

| Pattern | Intent | Context | |---------|--------|---------| | Dependency Injection | Supply dependencies externally rather than creating them internally | Enables testing, decoupling, and DIP compliance | | Null Object | Provide a no-op implementation instead of null checks | Eliminates if (x != null) scattered through code | | Repository | Collection-like interface for aggregate persistence | DDD — one repository per aggregate root | | Unit of Work | Coordinate writes across repositories in a single transaction | Ensuring consistency across multiple aggregates | | Specification | Composable, reusable business rule objects | Complex query/validation logic that must be combined |

---

When NOT to Use Patterns

Pattern-itis — applying patterns speculatively — is worse than the problems patterns solve.

• MUST NOT apply a pattern when only one implementation exists and no variation is foreseeable
• MUST NOT use a pattern the team does not understand — it becomes accidental complexity
• SHOULD NOT apply patterns preemptively — refactor toward patterns when complexity emerges (Kerievsky)
• SHOULD start with the simplest thing that works; introduce a pattern when the code smell appears

Norvig's observation: 16 of 23 GoF patterns are simplified or eliminated by dynamic language features. Before applying a pattern, ask: "Does my language already solve this?"

Decision Flow

1. Identify the specific code smell or design problem
2. Check if a language feature solves it natively (generics, lambdas, protocols, pattern matching)
3. If not, select the pattern whose intent matches the problem
4. Apply the simplest form of the pattern — avoid gold-plating
5. Verify the pattern improves readability and maintainability for the team

---

Checklist

Before applying or recommending a pattern, verify:

• [ ] A specific, recurring problem has been identified (not speculative future need)
• [ ] Language-native features have been considered first
• [ ] The selected pattern's intent matches the actual problem
• [ ] The pattern improves — not hinders — code readability for the team
• [ ] Singleton is NOT used (DI container manages lifecycle instead)
• [ ] Composition-based patterns are preferred over inheritance-based ones
• [ ] The pattern is applied in its simplest form without unnecessary abstraction layers
• [ ] The code compiles and passes tests after applying the pattern

Key References

| Book | Author(s) | Publisher | Year | |------|-----------|-----------|------| | Design Patterns: Elements of Reusable OO Software | Gamma, Helm, Johnson, Vlissides | Addison-Wesley | 1994 | | Head First Design Patterns (2nd ed.) | Freeman & Robson | O'Reilly | 2021 | | Patterns of Enterprise Application Architecture | Martin Fowler | Addison-Wesley | 2002 | | Refactoring to Patterns | Joshua Kerievsky | Addison-Wesley | 2004 | | Dive Into Design Patterns | Alexander Shvets | Refactoring.Guru | 2021 | | Game Programming Patterns | Robert Nystrom | Genever Benning | 2014 | | Fundamentals of Software Architecture | Mark Richards, Neal Ford | O'Reilly | 2020 | | Software Architecture: The Hard Parts | Ford, Richards, Sadalage, Dehghani | O'Reilly | 2021 |