A Philosophy of Software Design Summary: Deep Modules Beat Small Ones

Picture a codebase where adding one field means editing seven files, and nobody is sure which seven. No single commit made it that way. It got there one reasonable shortcut at a time.

That slow slide is what this book is about.

Book: A Philosophy of Software Design, John Ousterhout (2nd edition, 2021). Ousterhout is a Stanford professor who created the Tcl language, and the book grew out of a software design course he teaches there.

The book in one sentence#

Complexity is the enemy, and the best weapon against it is modules that hide a lot behind a simple interface.

Everything else in the book either explains where complexity comes from or gives you a way to hide it.

Idea 1: Complexity is anything that makes code hard to change#

Ousterhout defines complexity by its effect: anything that makes a system hard to understand or modify. He names three symptoms:

• Change amplification: one small change needs edits in many places.
• Cognitive load: you have to hold a lot in your head to make a change safely.
• Unknown unknowns: you can't even tell what you need to change. This is the worst one.

And two causes: dependencies (code that can't be understood alone) and obscurity (important information that isn't obvious).

The key point: complexity is incremental. No single shortcut ruins a codebase, so every shortcut feels fine.

Use it: in code review, ask "does this make the next change harder?" instead of "does this work?"

Idea 2: Be strategic, not tactical#

Tactical programming means getting the current feature working as fast as possible. Strategic programming means treating working code as not enough: the real goal is a design that keeps future changes cheap.

The book's name for the extreme tactical developer is the tactical tornado: someone who ships features fast and leaves a mess for everyone else, often while being praised as the most productive person on the team.

Ousterhout's suggestion is modest: spend about 10–20% of your development time on design improvements. Not a rewrite, just a steady investment that pays back within months.

Use it: when you touch a file, leave its design slightly better than you found it, and count that as part of the task.

Idea 3: Deep modules beat shallow ones#

This is the idea the book is known for.

Think of a module (a function, class or service) as a rectangle. The top edge is its interface: what you must learn to use it. The area is its functionality: what it does for you.

• A deep module has a small interface and a lot of functionality. The book's classic example is Unix file I/O: a handful of calls (open, read, write, lseek, close) hide disks, caching, permissions and file systems.
• A shallow module has an interface almost as complex as what it does. Calling it saves you little.

A deep module is a light switch: one simple control in front, all the wiring hidden in the wall. Photo: Kurtkaiser, CC0, via Wikimedia Commons

Here's the difference in TypeScript (this example is not from the book):

// shallow: three calls, and the caller must know the order and the format
const raw = readFileSync(path, "utf8");
const parsed = parseJson(raw);
const config = applyDefaults(parsed);

// deep: one call, the rest is hidden
const config = loadConfig(path);

The book also names the failure mode of "small is always good": classitis, where a codebase splits into many tiny classes, each easy to read alone but with so many interfaces that the system as a whole is harder to learn.

Use it: judge a function by how much it hides, not by how short it is.

Idea 4: Hide information, and watch for leaks#

Each module should own a design decision (a file format, a protocol, a caching rule) so the rest of the code doesn't need to know it. That's information hiding.

The opposite is information leakage: the same decision shows up in several places. If two modules both know the layout of a file, changing the layout means changing both.

A common cause is temporal decomposition: splitting code by the order things happen ("read, then process, then write") instead of by what knowledge each part owns. The reader and writer end up sharing the format.

Use it: before splitting a module, ask "what knowledge does each piece own?" If the answer is "the same thing", keep them together.

Idea 5: Define errors out of existence#

Every error a function can throw is part of its interface, and every caller has to deal with it. So the best error handling is often an API where the error can't happen.

JavaScript has good examples (these are not from the book):

"abc".slice(1, 100); // "bc"  ← clamps instead of throwing
new Set([1]).delete(5); // false ← "make sure 5 isn't there" always succeeds

The book's own example is a Tcl command Ousterhout regrets designing: removing a variable that didn't exist threw an error, so callers wrapped it in error handling. Defining it as "make sure this variable doesn't exist" would have removed the error entirely.

Use it: when you add a throw, ask whether a different definition of the operation would make the case normal instead.

Where it's weak#

• It disagrees with Clean Code, and both sides have a point. Ousterhout argues that very short functions and "self-documenting code with no comments" often make systems harder to understand. Robert Martin disagrees. The two discussed it at length in a public conversation from 2024–2025. Read both before adopting either as a rule.
• "Deep" can be misread as "big". A 2,000-line class with a two-method interface is deep, and also hard to work on. The book wants deep and well organized inside.
• It's light on testing. It's skeptical of test-driven development, arguing it pulls attention toward getting features working rather than finding the best design. Many teams won't agree.
• Few web examples. Most examples come from systems code and student projects. You'll need to translate them to frontend work yourself.

Use it on Monday#

1. In your next PR, name one place where you hid something from callers.
2. Find a function whose callers always call two other functions right after it. Merge them into one deep call.
3. Pick one throw in your code and see if a broader definition removes it.
4. Before building a module, sketch two different interfaces and compare them. The book calls this "design it twice".
5. Write the comment for a function's interface before the code. If the comment is hard to write, the design isn't clear yet.

Say it in an interview#

"I like Ousterhout's idea of deep modules: a good abstraction has a simple interface and hides a lot of functionality behind it. Complexity shows up as change amplification, cognitive load and unknown unknowns, and it builds up one shortcut at a time, so I try to work strategically: spend some of every task improving the design, hide design decisions inside one module, and design APIs so common error cases simply can't happen."

Cheat sheet#

Should you read it?#

Read it if you've written code for a year or more and feel your designs get messy as they grow. It's short, a weekend's reading, and written plainly.

Short on time? Read the chapters on complexity, deep modules, information hiding and errors. That's most of the value.

Skip it if you want a catalog of patterns or framework advice. It's about how to think, not what to type.

The author's page for the book: A Philosophy of Software Design.