Software Design Philosophy

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.

---

III. Deep Modules: The Most Important Design Concept

Core Metaphor

Think of a module as a rectangle:

• Width = complexity of its interface
• Height/Depth = amount of functionality hidden inside

Deep module: simple interface, rich implementation. (Good design) Shallow module: complex interface, does very little. (Bad design 🚩)

Classic Examples

• Deep: Unix file I/O — just 5 syscalls (open, read, write, lseek, close) expose a powerful file system.
• Shallow: Java I/O — reading a file requires composing FileInputStream, BufferedInputStream, ObjectInputStream, etc.

Practical Principles

• Design interfaces so the most common usage is as simple as possible.
• A simple interface matters more than a simple implementation.
• Rare use cases can accept more complex calling patterns, but the common path should never pay for them.

---

IV. Information Hiding and Information Leakage

Information Hiding

• Each module should encapsulate design decisions (knowledge), exposing only a simplified interface.
• Hidden information includes: data structures, algorithms, low-level mechanisms, policy decisions.
• Information hiding minimizes inter-module dependencies.

Information Leakage 🚩 Red Flag

• When the same design decision is reflected in multiple modules, information has leaked.
• Temporal decomposition is a common source: splitting modules by execution order (rather than by information hiding) causes steps to share excessive knowledge.

Fixing Leakage

• Merge shared knowledge into a single module.
• If merging isn't possible, unify the shared information behind a single deep module.

---

V. General-Purpose vs. Special-Purpose Modules

Core Principle: General-purpose modules are usually deeper.

• A general interface is simpler than a specialized one because it covers more use cases with fewer methods.
• When designing a new module, ask: What is the most general-purpose interface that can satisfy my current needs?

Judgment Criteria

• The interface should be general enough to support multiple use cases without modification.
• But the implementation can do only what's currently needed (don't over-build).
• General-purpose and special-purpose code should be cleanly separated.

---

VI. Different Layers, Different Abstractions

Principle

• A software system has multiple layers; each layer should provide a different abstraction from its adjacent layers.
• If two layers have similar abstractions, the layering is wrong.

Pass-Through Method 🚩 Red Flag

• A method that does almost nothing except forward its arguments to another method with a similar signature.
• This signals that the layers don't offer different abstractions — the responsibility split is flawed.

Pass-Through Variable 🚩 Red Flag

• A variable threaded from top to bottom through layers that don't use it.
• Solutions: context objects, dependency injection, or rethinking module boundaries.

---

VII. Pull Complexity Downward

Core Principle

• When complexity is unavoidable, the module should absorb it internally rather than pushing it to callers.
• Most modules have more users than developers — it's better for developers to suffer than for every user to suffer.

Anti-patterns

• Turning hard decisions into configuration parameters and pushing them to sysadmins.
• Throwing exceptions for uncertain conditions and letting callers handle them.
• These save effort in the short term but amplify complexity system-wide.

---

VIII. Define Errors Out of Existence

Core Insight

• Exception handling is one of the biggest sources of complexity.
• Reducing the number of exceptions that must be handled is one of the best techniques for reducing complexity.

Strategies

1. Redefine semantics so the error condition cannot arise.

   • Example: unset(key) succeeds even if the key doesn't exist — it simply guarantees "after the call, the key does not exist."
   • Example: substring(start, end) auto-clips out-of-bounds parameters instead of throwing.

2. Exception Masking: Detect and handle exceptions at a low level so they never reach callers.

3. Exception Aggregation: Handle multiple exception types in one centralized place instead of scattering handlers at every call site.

Important Distinction

• This is not about ignoring errors — it's about designing better semantics so error conditions simply aren't errors.
• Errors that truly require reporting (e.g., lost network packets) must still be handled properly.

---

IX. Design It Twice

• For any important design decision, conceive at least two different approaches before choosing.
• Even if the first idea seems great, force yourself to think of an alternative.
• Comparison dimensions: interface simplicity, generality, performance, implementation difficulty.
• This habit significantly improves design quality.

---

X. The Philosophy of Comments

Why Write Comments

1. Comments capture design decisions and intent that code cannot express.
2. Comments are part of the abstraction — good interface docs mean users don't have to read the implementation.
3. Writing comments early exposes design problems before you invest in code.
4. Good comments dramatically reduce cognitive load.