software-design-philosophy

A module is shallow when its interface is nearly as complex as its implementation, meaning it adds cognitive load without hiding meaningful complexity. Compare the number of methods and parameters against the functionality hidden behind them; thin wrappers and pass-through methods are classic shallow signals.

Information leakage occurs when one design decision, such as a data format or protocol, is reflected in multiple modules. It creates hidden dependencies so a single change ripples across the codebase. The fix is to merge modules that share knowledge or extract the shared knowledge into one owning module.

Split only when the new class hides a distinct, significant design decision behind a simpler interface. Splitting by execution order or to satisfy small-class metrics creates classitis, where many shallow classes add interface overhead without depth. Depth matters more than size.

Configuration parameters push decisions onto callers, multiplying complexity across every user of the module. Prefer sensible defaults, auto-detection, or eliminating the parameter entirely. Keep parameters only when callers genuinely need different values and the module cannot determine the right one.

The strategic programming approach recommends investing roughly 10-20% of development time in design improvement as part of every change, not as separate refactoring phases. Small continuous investments compound, while tactical shortcuts accumulate into debt that slows the whole team.

Self-documenting code covers low-level implementation details but cannot express abstractions, design rationale, constraints, or cross-module relationships. Interface comments that describe what a module promises remain essential; write them before the implementation to validate the design.