A Philosophy of Software Design Framework

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: