Guides
The ideas behind the catalogues: what a pattern is, where patterns go wrong, how refactoring works, and how to pick the smallest fix.
Design patterns
- What Is a Design PatternA design pattern is a named, reusable solution shape for a recurring design problem. Learn what one contains and how it differs from an algorithm or library.
- History of PatternsWhere design patterns came from, from Christopher Alexander's architecture books to the Gang of Four catalog, and what changed in how they are used today.
- Why Learn PatternsWhat knowing design patterns buys a developer or coding agent: shared vocabulary, faster code reading, better refactoring targets, and knowing when to stop.
- Criticism of PatternsThe main arguments against design patterns, including missing language features, misuse, and over-engineering, and how to apply patterns without those failures.
- Classification of PatternsHow the 22 classic design patterns are grouped by purpose into creational, structural and behavioral, plus other useful ways to slice them.
- Factory ComparisonTell apart a factory function, static creation method, simple factory, Factory Method and Abstract Factory, and pick the smallest one that fits.
- Visitor and Double DispatchWhy overloading alone cannot pick a method by an argument's runtime type, how Visitor uses double dispatch to fix it, and when pattern matching replaces it.
- Choosing a PatternA decision guide that maps concrete code symptoms to the pattern that fixes them, and tells you when plain code beats any pattern.
- Eval-Driven DevelopmentWrite the task-and-verifier pairs before the tool, prompt or agent, then let the numbers decide changes - the same discipline as tests-first, applied to components whose output is text.
Refactoring
- How Agents Should Use This ReferenceRules for AI coding agents using this reference: diagnose a named smell, read the exclusions first, apply one technique at a time and verify with tests.
- What Is RefactoringRefactoring changes the internal structure of code in small, behavior-preserving steps so it becomes cheaper to read and change.
- Technical DebtTechnical debt is the extra cost every future change pays because of shortcuts and drift in today's code. Learn its causes and how to pay it down.
- When to RefactorRefactor right before you change code, while fixing a bug and during review. Skip it when the code is due for deletion or has no tests.
- How to RefactorRefactor in small named steps, run tests after each one, never mix in behavior changes, and stop when the code is clean enough for the task at hand.