Software Design Philosophy

A Philosophy of Software Design Framework

A practical framework for managing the fundamental challenge of software engineering: complexity. Apply these principles when designing modules, reviewing APIs, refactoring code, or advising on architecture decisions.

Core Principle

The greatest limitation in writing software is our ability to understand the systems we are creating. Complexity is the enemy: it makes systems hard to understand, hard to modify, and a source of bugs. Evaluate every design decision by asking "Does this increase or decrease the overall complexity of the system?" — the goal is not zero complexity, but minimizing unnecessary complexity and concentrating the necessary kind where it can be managed.

Scoring

Goal: 10/10. When reviewing or creating a design, score it by counting how many of the eight Quick Diagnostic rows it satisfies (≈1.25 points each), then sanity-check against the bands:

• 9-10 — deep modules with interfaces far simpler than implementations; no information leakage (an implementation can change without touching callers); interface comments capture design intent; design improvement is routine. All eight diagnostics pass.
• 6-8 — mostly deep, but one or two leaks, shallow classes, or undocumented abstractions. 5-6 diagnostics pass.
• 3-5 — classitis or temporal decomposition, recurring leakage, comments that only restate code. 2-4 diagnostics pass.
• ≤2 — tactical-tornado code: shallow modules, pervasive leakage, no design intent recorded. 0-1 diagnostics pass.

Always state the current score, the diagnostic rows that failed, and the specific change each one needs to reach 10/10.

The Software Design Framework

Six principles for managing complexity and producing systems that are easy to understand and modify:

1. Complexity and Its Causes

Core concept: Complexity is anything about a system's structure that makes it hard to understand and modify. It shows three symptoms — change amplification, cognitive load, and unknown unknowns — and has two causes: dependencies and obscurity.

Key insights:

• Change amplification: a simple change requires edits in many places
• Cognitive load: a developer must hold too much in mind to make a change
• Unknown unknowns: it isn't obvious what must change or what information is relevant — the worst symptom
• Complexity is incremental — it accumulates from hundreds of small decisions ("death by a thousand cuts"), so every decision matters

Code applications:

See references/complexity-symptoms.md when you need to name which symptom a codebase has before fixing it — per-symptom recognition tests, the dependency taxonomy (syntactic/semantic/temporal/hidden), the C = Σ(cp·tp) cost formula, and a 10-row red-flag table.

2. Deep vs Shallow Modules

Core concept: The best modules are deep: powerful functionality behind a simple interface. Shallow modules have complex interfaces relative to the functionality they provide — they add complexity rather than hiding it.

Why it works: The interface is the cost a module imposes on the rest of the system; the implementation is the benefit. So a method that is harder to learn than to re-implement yourself is net-negative — depth, not line count, decides whether a module earns its place.

Key insights:

• Depth = functionality provided / interface complexity imposed (Unix file I/O is deep; thin Java I/O wrappers are shallow)
• "Classitis": the disease of creating too many small, shallow classes — each interface adds cognitive load
• Small methods are not inherently good; depth matters more than size
• The best abstractions hide significant complexity behind a few simple concepts

Code applications:

See references/deep-modules.md when judging whether an abstraction pulls its weight — before/after code for the depth ratio, the classitis cure worked out, and case studies (Unix I/O, GC, TCP/IP).

3. Information Hiding and Leakage

Core concept: Each module should encapsulate knowledge not needed by other modules. Information leakage — one design decision reflected in multiple modules — is one of the most important red flags in software design.

Why it works: A decision that lives in one module can change there and nowhere else; the same decision leaked into N modules turns one edit into N edits that no compiler will remind you to make. Hiding is what converts change amplification back into a local change.

Key insights:

• Temporal decomposition causes leakage: splitting code by when things happen forces shared knowledge across phases — organize by knowledge instead
• Back-door leakage through data formats, protocols, or shared assumptions is the subtlest form
• Decorators frequently leak — they expose the decorated interface
• If two modules share knowledge, merge them or create a new module that encapsulates it

Code applications:

See references/information-hiding.md when a change forces you to edit two modules in lockstep — the four leakage forms with code (interface, back-door, temporal, decorator), five reduction strategies, the HTTP-handling case study, and a detection table.

4. General-Purpose vs Special-Purpose Modules

Core concept: Design modules that are "somewhat general-purpose": an interface general enough to support multiple uses, with an implementation that handles current needs. Ask: "What is the simplest interface that will cover all my current needs?"

Why it works: Counterintuitively, the general interface is usually the simpler one — special-case methods multiply as requirements grow, while one general method absorbs them. The trap is the other direction: generality the current needs don't demand is speculative complexity, paid now for a use case that may never arrive.

Key insights:

• "Somewhat general-purpose" is the sweet spot between too specific and too generic
• Push complexity downward: lower-level modules should handle hard cases so upper levels stay simple
• Configuration parameters often represent a failure to decide — each parameter is complexity pushed onto the caller
• When in doubt, implement the simpler, more general-purpose approach first

Code applications:

See references/general-vs-special.md when choosing how general an interface should be — the "simplest interface for all current needs" test, the configuration-parameter antipattern, and push-complexity-downward worked through.