A Philosophy of Software Design

Complexity is the enemy: anything that makes code hard to understand or modify, weighted by interaction frequency
Three symptoms: change amplification, cognitive load, unknown unknowns (worst)
Two causes: dependencies and obscurity
Two strategies: eliminate complexity (simpler code) or encapsulate it (deep modules with simple interfaces)
Investment mindset: spend 10-20% of development time on design; it compounds and eventually costs nothing extra

Situation	Do This	Avoid This
Designing a module	Make it deep: powerful functionality, simple interface	Shallow modules with complex interfaces (classitis)
Choosing what to expose	Hide implementation decisions behind the interface	Information leakage across module boundaries
Handling exceptions	Define errors out of existence; redefine semantics	Adding exceptions that callers must handle
Writing comments	Describe what's NOT obvious: precision + intuition	Repeating what the code already says
Starting implementation	Write interface comments first, then code	Writing code first, documenting later
Structuring layers	Each layer should offer a different abstraction	Pass-through methods that mirror the layer below
Facing unavoidable complexity	Pull it downwards into the module	Pushing complexity up to callers
Naming things	Be precise and consistent; if naming is hard, redesign	Vague names or inconsistent conventions
Modifying existing code	Treat every change as a design opportunity	Tactical patches that degrade structure
Evaluating a trend	Ask: does this reduce complexity in my context?	Dogmatic adoption without complexity analysis

"The greatest limitation in writing software is our ability to understand the systems we are creating." — John Ousterhout, Chapter 1

Overview