A Philosophy of Software Design and its sharpest critics

Deep modules is an idea I keep thinking about.. a small interface with the hard stuff hidden behind it. It’s the one I see most in my own personal work and in my professional line of work. Strategic vs tactical programming as well.

The book is John Ousterhout’s A Philosophy of Software Design, which has been out in its 2nd edition since 2021. The sharpest counterpoints I’ve seen to it are in his written debate with Robert C. Martin, the Clean Code author.. that debate got 542 comments on Hacker News. Deep modules are already all over the place in the tools I rely on, as this thread on r/ExperiencedDevs points out. The file system, for example, and mutexes.. just a few simple calls, lots hidden behind. The top comment there says the book’s popularity is a swing back away from Clean Code.

The deep module idea

In chapter 4, Ousterhout argues that the best modules provide lots of functionality through a simple interface, and that creating many small classes (“classitis”) adds complexity. Eric Normand objects to this idea, saying “Module depth is an attempt to rationalize an intuition. However, it is a dangerous idea.” The most common objection in this r/softwarearchitecture thread is that the examples in the book are small, contained projects, while real systems sprawl across many. That same thread also tries to reconcile the two books by saying Ousterhout is talking about modules and Martin is talking about classes, and a deep module can be made of small single-purpose pieces. In practice, I’ve been designing skills and services with a simple front and lots of complexity behind because agents write a lot of the code, so keeping the interface small makes it easier to review. This idea is packaged up for agents by Matt Pocock in this skills repo.

Tactical tornadoes

In chapter 3, Ousterhout says that it’s not enough to just write working code.. you should spend some time thinking about the design. He warns about the “tactical tornado”, where you ship features quickly and other people have to clean up your mess. Yevgeniy Brikman counters with “the book doesn’t seem to acknowledge there are contexts when tactics are a better option”, like when you’re doing quick experiments and the code will be thrown away in a few weeks or months. Coding agents make this question even more interesting.. olano.dev argues that tactical tornado is the new default when more work is delegated to agents.

The comments debate

Chapters 12 to 16 discuss comments and how they can capture the mind of the designer and things that code can’t say. Section 16.3 says comments belong in code, because a developer “is unlikely to think of scanning the repository log”. Martin’s response in the debate was “Comments are always failures.” But since then, coding agents have introduced many comments themselves. An issue asking Claude Code to stop over-commenting has 252 reactions and notes that a CLAUDE.md rule “does not reliably suppress it”. And a study of LLM-written comments found that experts rated most of them as good as or better than the originals.

So for comments: in my repos the commit history, ADRs and a CLAUDE.md carry the why more than inline comments do. Agentic coding models tend to lean hard on comments, so we are seeing an uprising in them now. For better or worse.