Mastering Software Design: Proven Strategies to Reduce Complexity

1. Introduction

John Ousterhout’s book A Philosophy of Software Design has been praised for presenting universal principles that form a cohesive design philosophy. The core idea is that software design aims to reduce complexity.

2. Defining Complexity

Complexity lacks a single definition. It can be measured by quantity (e.g., number of components), hierarchical recursion, or information entropy. Ousterhout defines software complexity as the cognitive burden and development effort required, proposing a formula where each sub‑module’s complexity C p is multiplied by its development‑time weight t p , and the sum yields the system’s overall complexity C.

The complexity of a sub‑module depends on three phenomena: modification ripple, cognitive load, and “unknown unknowns” (situations where developers don’t know where to start). Complexity often stems from code dependencies and obscurity.

3. General Principles for Reducing Complexity

Software systems in the internet industry evolve iteratively; perfect design is rarely achieved upfront. Continuous investment in design details gradually improves the system. Professional specialization and code reuse increase productivity by separating concerns into layers and modules.

Layered architecture reduces per‑layer complexity, while modularization (e.g., micro‑services) isolates functionality but introduces new inter‑module complexity that must be managed.

Comments and documentation capture design intent, lowering cognitive load and mitigating “unknown unknowns”. Good comments act as a design tool, revealing high‑level intent without exposing internal implementation details.

3.1 Reject Tactical Programming

Tactical programming focuses on quick fixes, which accumulates hidden complexity. Strategic programming invests time in design, sacrificing short‑term speed for long‑term maintainability.

3.2 Design Twice

Providing multiple design alternatives helps identify the optimal solution. A robust technical proposal should answer why a solution is feasible and why it is optimal given constraints, often by presenting two to three competing designs.

4. Layering

Layered systems expose interfaces only to adjacent layers, limiting the impact of changes and simplifying maintenance. The TCP/IP model exemplifies clear abstraction at each layer.

4.1 Complexity Sinking

Complexity should be hidden from users; when necessary, it is better handled at lower layers (e.g., internal retry mechanisms) rather than exposing configuration burdens to downstream developers.

5. Modularization

Modules should be isolated so developers only need to understand a small part of the system. Deep modules provide powerful functionality behind simple interfaces, while shallow modules expose complex interfaces for simple functionality, often adding unnecessary cognitive load.

5.1 Deep vs. Shallow Modules

Deep modules (e.g., Unix open system call) hide extensive implementation details behind a concise API. Shallow modules (e.g., Java I/O streams) require developers to manage multiple objects, increasing effort.

int open(const char* path, int flags, mode_t permissions);

FileInputStream fileStream = new FileInputStream(fileName);
BufferedInputStream bufferedStream = new BufferedInputStream(fileStream);
ObjectInputStream objectStream = new ObjectInputStream(bufferedStream);

5.2 General vs. Specific Modules

General modules serve many scenarios, reducing future rework, while specific modules address immediate needs quickly. A balanced approach designs specific functionality now while keeping interfaces general for future extension.

5.3 Information Hiding

Modules should encapsulate internal logic, exposing only necessary interfaces. This reduces cognitive load and inter‑module dependencies, as illustrated by database index implementations hidden behind SQL.

5.4 Split and Merge

Decide whether related functionality belongs together or should be separated based on shared information, interface simplicity, and duplication removal.

6. Commenting

Comments capture design rationale and system behavior, lowering cognitive burden and aiding maintenance. Effective comments focus on the “what” and “why” rather than the “how”, and should be written early in the development process.

6.1 Common Misconceptions

Many developers believe good code is self‑documenting or lack time for comments. However, without explicit commentary, design intent is often lost, especially in complex modules.

6.2 Improving Maintainability with Comments

Comments should provide information not evident from code, distinguishing low‑level details (units, boundaries) from high‑level overviews (module purpose). High‑level comments remain stable across implementations.

6.3 Using Comments to Refine Design

Writing comments before coding forces abstraction, helping identify core module responsibilities. Overly verbose interface comments signal excessive complexity; concise comments indicate a well‑designed API.

7. Conclusion

John Ousterhout’s 250,000 lines of code experience underpins these principles, which align with other classic works such as “Code Complete” and “Domain‑Driven Design”. The guidelines offer practical value for engineers seeking to reduce complexity and improve software quality.