software-design-philosophy

Compare the interface complexity to the functionality provided. If a method is harder to learn than to re-implement yourself, or a class only forwards calls to another class, the module is shallow and adds cognitive load without hiding meaningful complexity.

Information leakage occurs when one design decision is reflected in multiple modules, so changing it requires editing all of them. Common forms include interface leakage, back-door leakage through shared data formats, temporal decomposition, and decorator patterns that duplicate wrapped interfaces.

Write comments for what code cannot express: design intent, abstraction contracts, invariants, and cross-module constraints. Interface comments are the most important type. Skip comments that merely restate what the code already makes obvious.

The strategic programming approach recommends investing 10-20% of development time in design improvement as part of every change, not as separate refactoring phases. Small continuous improvements compound, while tactical shortcuts accumulate into crippling complexity.

Aim for somewhat general-purpose: the simplest interface that covers all current needs. General interfaces are usually simpler than collections of special-case methods, but avoid speculative generality for hypothetical future requirements.

The framework provides qualitative heuristics rather than automated metrics, so scoring depends on judgment. It addresses module-level and interface design, not system-level architecture boundaries, which require separate architectural analysis.