Book Club: Reflections on A Philosophy of Software Design

This is not a summary of John Ousterhout’s book, A Philosophy of Software Design . It is a reflection on where the principles of John Ousterhout resonate, where I push back, and what it looks like applied to real production codebases rather than academic ones. The Running Example To keep the ideas concrete, I will use the same example throughout: a distributed database storage engine. It needs to write records durably, survive crashes, and maintain consistency. Under the hood that means a B+ tree for indexed lookups, a write-ahead log for crash recovery, and careful ordering of operations to guarantee nothing is lost. It is a domain with genuine complexity, subtle constraints, and real consequences for getting the design wrong, which makes it a good lens for everything Ousterhout is talking about. For a storage engine, a clean interface exposes only a few basic operations: // StorageEngine represents a deep module with a simple interface. type StorageEngine interface { Get(key []byte) ([]byte, error) Put(key []byte, value []byte) error Delete(key []byte) error } Behind this interface lies the actual implementation complexity: the WAL, index, caching, and checksum validation. The Core Idea: Complexity Lives in Modules Ousterhout’s central argument flips conventional wisdom. Most engineers are taught that small is always better: small units of code, small functions, single responsibility everywhere. Ousterhout says that is the wrong unit of measurement. What matters is not size but the ratio of interface to implementation. A deep module has a simple, narrow interface and a rich, well-hidden implementation. A shallow module has an interface nearly as complex as what it hides. The shallow module is the problem. You pay the cost of the abstraction without getting the benefit. In our storage engine, get, put, and delete form the narrow interface. The B+ tree, the write-ahead log, the page cache, and the checksum validation are hidden from the caller: graph TD Client[Client Code] Client -->|Simple API: Get/Put/Delete| Engine[Storage Engine Interface] subgraph impl[Deep Module Implementation] Engine --> WAL[Write-Ahead Log] Engine --> BTree[B+ Tree Index] Engine --> Cache[Page Cache] Engine --> Checksum[Checksum Validator] end One clarification worth making: internal decomposition does not violate this principle. The storage engine can have a page manager, a log flusher, and a checksum validator internally, and still be a deep module, as long as those components are hidden behind the top-level interface. The failure mode is when those internal components get exposed directly to callers, each requiring the consumer to understand and coordinate them. You have not reduced complexity. You have just moved it from inside the module to the space between modules, where it is harder to see and harder to manage. The Reusability Illusion The reason “small is always better” became doctrine is reusability. Extract small pieces, compose them freely, reuse everywhere. In theory this is elegant. In practice it creates two problems. First, if a piece of functionality is too small and too specific, it is not actually reusable. Extracting validateChecksumForLeafNodes() into a shared utility feels like good practice. But if it is called from exactly one place, you paid the cost of indirection without getting the benefit. Second, extreme atomization destroys discoverability. When everything is a micro-function, you cannot know what already exists. You search, find nothing obvious, and recreate it. Now the codebase has two implementations of checksum validation, diverging silently over time. A larger, well-named module with clear ownership is paradoxically more discoverable. You know that write durability logic lives in the storage engine module. You go there first. On Long Methods: Where I Disagree Ousterhout argues that method length is not itself a problem. A 500-line method with a clean single-concept signature can be better than 20 tiny methods you have to jump between. I understand the argument and I disagree with it. To be fair to Ousterhout, his actual concern is about state passing. When you split a naturally sequential block of logic across many small functions, you have to thread state through arguments or shared references across artificial boundaries. That is a real cost and a real source of bugs. I am not dismissing it. But I think the costs of long methods outweigh it. First: complexity hides in long methods. A long method is a low-resistance path for accidental complexity to accumulate. Someone adds a condition here, an early return there, a side effect tucked in the middle. Each change is small and local, so it flies under review radar. A write() method that starts at 100 lines will be 400 lines in two years, with WAL flushing, page commits, tree rebalancing, and cache invalidation all tangled together. Shorter, named functions have a natural complexity ceiling. It is hard to hide a disaster in 20 lines. Second: navigation. When I am debugging a crash recovery failure, I do not care about the tree rebalancing logic or the cache eviction strategy. A long method forces me to read everything to find the part I need. Well-named extracted functions act as a table of contents: flushWAL(), commitPage(), rebalanceTree(), invalidateCache(). I go straight to the relevant one. Ousterhout suggests using comments to mark sections inside a long method, but that is simulating what extraction gives you for free, with worse tooling support. You cannot navigate to a comment, you cannot see a comment in a stack trace. For instance, compare a single massive method with a self-documenting call sequence: func (s *storageEngine) Put(key, value []byte) error { if err := s.writeAheadLog.Append(key, value); err != nil { return fmt.Errorf("wal append failed: %w", err) } if err := s.pageCache.Write(key, value); err != nil { return fmt.Errorf("cache write failed: %w", err) } return nil } Third: stack traces. In synchronous, thread-per-request systems, which covers the majority of backend Java and Go services, a well-decomposed call stack is free structured logging of intent. When something fails in production, writeRecord -> flushWAL -> commitPage -> invalidateCache tells a story before you have read a single line of code. A monolithic write() gives you one frame and then silence. This argument does not hold equally in async runtimes where futures and event loops detach the stack from execution intent. In those environments, explicit semantic logging matters more than decomposition for production debugging. But for synchronous code, decomposition wins. Fourth: cognitive load. Real codebases are written by people at different experience levels, under different pressures, over years. A less experienced engineer opening a 500-line write() is far more likely to introduce an invisible bug, breaking a subtle ordering constraint, for instance, than someone working in a 30-line flushWAL() with a clear single purpose. My overall mental model: I approach code from the perspective of someone who has never seen the codebase. What communicates intent most clearly to that person? That question almost always favors explicit, named, decomposed functions over clever compression. On Comments: Useful but Fragile Ousterhout is a strong advocate for comments encoding information the code cannot express: the why behind decisions, the non-obvious invariants, the constraints that hold across the system. I agree with the principle and have reservations about the practice. The core problem is that comments have no enforcement mechanism. Code gets refactored, comments do not. A stale comment is worse than no comment. It causes the reader to reason from a lie. Tests at least break when they contradict the code. Comments silently decay. In the storage engine, the WAL must be flushed and confirmed durable before the page is committed to the B+ tree. If the order is reversed and the process crashes between the two operations, the page write is unrecoverable. That constraint is worth documenting. But if someone later refactors the write path and forgets to update the comment, a future engineer will reason from a description of ordering guarantees that no longer hold, possibly for months before a crash surfaces the bug. I have never worked in a codebase that successfully maintained its comments over time. That is not a personal failure. It is a structural one. The environments where comments are most valuable (large teams, high turnover, time pressure) are exactly the environments least likely to maintain them. My pragmatic position is a triage approach: Public interfaces — comment deliberately, treat the comment as a contract. Breaking the behavior is a conscious decision that updates the comment. Configuration and contract types — when a class or structure defines configuration properties or serves as a shared contract between components, comments on the fields earn their place. A well-commented configuration class tells you what each property controls, what the valid range is, and what happens if you leave it unset. Hovering over a configured property in an editor and seeing a clear description saves you from tracing source code to understand what a field actually does. Non-obvious constraints — comment sparingly but intentionally. Ordering dependencies, cross-component invariants, things that cannot be expressed in any naming scheme. Everything else — trust naming, let the code speak. One specific Ousterhout recommendation I want to push back on: using ticket numbers in comments. The intent is good, give context without restating everything inline. And there is a real case for it. A ticket reference can be an immutable historical marker, linking to the original discussion, benchmarking results, and PR review that explain why the code was written the way it was. That is context an inline comment can rarely fit and an ADR rarely captures at that level of detail. The problem is reliability. Ticketing systems migrate. Tickets get archived or deleted. New engineers may not have access. What was an immutable marker becomes a dead link. My preference is to encode the essential reasoning directly in the comment, and add the ticket reference as supplementary context rather than a substitute for it. The comment should still make sense if the link rots. Architecture Decision Records complement comments well for structural decisions: why the storage engine uses a WAL rather than shadow paging, why event-driven integration was chosen over direct calls. These belong in ADRs rather than inline comments. They are persistent, versioned, and survive refactors. Lower-level decisions, like a specific configuration value chosen during performance tuning, belong closer to the code itself, either as a configuration comment or an inline note. ADRs should not be broken by a single-commit parameter tweak. The practical combination looks like: ADRs for architectural why, interface comments for contracts and intent, implementation comments for non-obvious constraints, good naming for everything else. Tactical vs Strategic Programming Ousterhout distinguishes between tactical programming, doing whatever ships the feature fastest, and strategic programming, investing in design quality as you go. The argument is that tactical shortcuts compound into complexity that costs more to maintain than the shortcuts ever saved. This resonates strongly. A storage engine accumulated through tactical decisions, add range scan support here, bolt on a cache there, handle this edge case with a special flag, ends up as something nobody fully understands. No single decision felt wrong. The accumulation becomes unmanageable, and the subtle ordering constraints that were obvious to the original author are now landmines for everyone else. The book does not offer a quick fix for this, and honestly there is not one. What it does offer is a clearer way to think about the cost of each shortcut: not as a one-time saving but as a tax paid on every future change to that area of the codebase. I write more about the inevitable accumulation of this complexity in Every System Rots. Some Rot Better Than Others. . Design It Twice (or Three Times) One of the more actionable ideas in the book: before committing to a design, design an alternative and compare. The act of comparison forces you to articulate what is actually good about each approach, rather than going with the first shape the problem took in your mind. I have done this with the storage engine itself. I implemented the write path, discovered I did not fully understand the edge cases around concurrent writes and crash recovery, deleted the whole thing and started from scratch. The first implementation was a thinking tool, not the deliverable. The second was built on complete understanding of the problem space. There is a related idea that the first pass reveals the problem, the second reveals the solution, and the third is where you build for real. It sounds wasteful. For anything non-trivial it is probably the most time-efficient approach. Two throwaway passes are cheap compared to years of maintaining a system built on incomplete understanding. What Sticks The book is most useful not as a rulebook but as a sharpened instinct. You cannot always apply it to the codebase you are in, especially when inheriting years of accumulated decisions. But it gives you a clearer eye for what to do when you do get space to design something from scratch. The ideas I keep coming back to: Complexity lives in modules, measure the interface not the size Fresh eyes: would someone unfamiliar understand this cold? Dumb and explicit beats clever every time Comments are valuable but fragile, minimize the surface area that needs maintaining Design twice (or three times) The long methods disagreement aside, it is one of the more honest and useful software design books I have read, precisely because it is willing to be opinionated rather than comprehensive.