Design Heuristics and Smells

Software design doesn’t come with a rulebook that covers every situation. Instead, experienced practitioners develop heuristics, rules of thumb that guide decisions when the “right” answer depends on context. This section lives at the heuristic level: the layer of taste, judgment, and pattern recognition that separates adequate code from code that’s pleasant to work with over time.

Heuristics aren’t laws. They conflict with each other, they admit exceptions, and they require judgment to apply well. “Keep it simple” is excellent advice until simplicity means duplicating the same logic in twelve places. The skill is knowing when each heuristic applies and when to set it aside.

This section also introduces smells, surface symptoms that suggest something deeper may be wrong. A code smell doesn’t prove a defect exists; it raises a question worth investigating. In the agentic coding era, a new category of smell has emerged: patterns in AI-generated output that suggest the model optimized for plausibility rather than understanding. Learning to recognize both kinds of smell makes you a better reviewer, whether you’re reviewing human work or agent output.

This section contains the following patterns:

• KISS — Keep it simple. Remove needless complexity.
• YAGNI — You aren’t gonna need it. Resist speculative generality.
• Local Reasoning — Understanding a part without loading the whole system into your head.
• Make Illegal States Unrepresentable — Design types and structures so invalid conditions cannot be expressed.
• Smell (Code Smell) — A surface symptom suggesting a deeper design problem.
• Smell (AI Smell) — A surface symptom that output was produced for plausibility rather than understanding.