A Philosophy of Software Design — Distilled Guide

---

name: software-design-philosophy description: > Software design philosophy guide based on John Ousterhout's "A Philosophy of Software Design." Use this skill during: code reviews, architecture discussions, API design, module decomposition decisions, refactoring guidance, complexity analysis, naming and commenting improvements, error handling strategy design. Trigger when the user mentions "code is too complex", "how to split modules", "interface design", "reduce coupling", "deep/shallow modules", "information leakage", "error handling", "code readability", "design philosophy", "pull complexity down", "define errors out of existence", or similar topics. Also trigger for any code review where design quality feedback is requested.

A Philosophy of Software Design — Distilled Guide

Source: John Ousterhout, *A Philosophy of Software Design* Central thesis: **The core challenge of software design is managing complexity.**

---

I. Complexity: Know the Enemy

Definition

Complexity is anything related to the structure of a software system that makes it **hard to understand and modify**. Complexity is not the same as system size — a small system can be complex, and a large well-designed system can be manageable.

Three Symptoms of Complexity

1. Change Amplification: A seemingly simple change requires code modifications in many different places.
2. Cognitive Load: Developers must absorb a large amount of information to complete a task safely. Note: fewer lines of code ≠ simpler — sometimes more code is actually simpler because it reduces cognitive load.
3. Unknown Unknowns: It's unclear which code must be modified or what information is needed to complete a task. This is the most dangerous symptom.

Two Root Causes

1. Dependencies: A piece of code cannot be understood or modified in isolation; it relates to other code that must also be considered.
2. Obscurity: Important information is not obvious — vague names, missing docs, implicit conventions, hidden constraints.

Key Insight

• Complexity is incremental: It's not caused by a single catastrophic error; it accumulates through thousands of small decisions.
• Therefore you must adopt a zero-tolerance mindset — every bit of "minor" complexity matters.

---

II. Strategic vs. Tactical Programming

Tactical Programming (Anti-pattern)

• Goal: get features working as quickly as possible.
• Mindset: "Just make it work", "We'll refactor later."
• Result: complexity accumulates fast, tech debt spirals out of control.

Strategic Programming (Recommended)

• Goal: produce great design; working code is a byproduct.
• Mindset: invest roughly 10–20% of development time in design improvements.
• Practices:
  • Look for opportunities to improve design with every change.
  • Working code is not enough — design quality matters equally.
  • The increments of software development should be abstractions, not features.

---

II