software-design-philosophy

Evaluate the ratio of functionality to interface complexity: deep modules hide significant implementation behind simple interfaces, while shallow modules leak complexity outward. Check for change amplification, cognitive load, and unknown unknowns, then score the design 0-10 against the framework's principles.

A deep module provides powerful functionality behind a simple interface, like Unix file I/O. A shallow module has a complex interface relative to what it does, such as thin wrapper classes that just pass calls through. Depth matters more than method or class size.

Information leakage appears when the same design knowledge is reflected in multiple modules, such as shared data formats, protocols, or temporal decomposition splitting related logic across phases. Fix it by encapsulating the knowledge in a single module or merging the affected modules.

Choose a somewhat general-purpose interface when it covers all current needs with fewer special cases, such as one store(key, value) method instead of per-entity methods. Avoid over-generalization; the key question is what is the simplest interface covering current needs.

Self-documenting code only conveys low-level what, not why, design alternatives, or assumptions. Interface comments capturing the abstraction are essential; write them before the code using comment-driven design and keep them updated as the code evolves.