The design book to read before handing AI-written code to a client
In 196 pages, John Ousterhout teaches one discipline: hide complexity behind small interfaces, because the client lives with the code after you leave.

In brief
- Ousterhout argues that complexity is the real limit on software, and defines it as anything that makes code hard to understand or modify.
- He likens AI coding tools to tactical tornadoes: they write and fix code fast, but they create new bugs and technical debt as they go.
- Three ideas worth keeping for FDEs: deep modules, strategic rather than tactical thinking, and comments that say what the code cannot.
In April 2025, on The Pragmatic Engineer podcast, John Ousterhout compared AI coding tools to “tactical tornadoes”: quick to write code, quick to fix bugs, and just as quick to create new bugs and technical debt along the way.
For FDEs, the remark hits a nerve. You use AI to stand up an integration in a few days, then hand it over to the client’s engineering team, who have to read and change that code after you have moved on to another project.
In the same episode, Ousterhout suggested that the boom in AI coding may make software design more important than before. His 196-page book, A Philosophy of Software Design, is the most compact place to learn that kind of design.
196 pages against one enemy
The second edition was published by Yaknyam Press in July 2021, ISBN 978-1732102217. Its central subject is how to decompose a complex system into modules such as classes and methods. In an interview with Software Engineering Radio, Ousterhout put it bluntly: the only thing limiting what we can build in software is complexity.
His definition is practical: complexity is anything that makes a project hard to understand and hard to modify. FDEs can use it straight away, because “hard to understand, hard to modify” is exactly how a client engineer feels on opening the repository you left behind.
Deep modules are the lesson to keep
Ousterhout calls a module shallow when it has a lot of interface and little functionality. A deep module does the opposite, using a simple interface to hide complex functionality. Shallow modules make a system messier, because users have to invest effort in learning the interface and get very little in return.
Take a hypothetical case. You ask an AI to write a connector that pulls contacts from the client’s CRM, and the generated version has six public functions: get a token, refresh the token, build headers, retry a request, read the next page, normalize records. A client engineer who wants to use it has to understand all six and the right order to call them in.
The deep version exposes a single function, something like fetch_contacts(since), with authentication, retries and pagination tucked inside. What the person taking over has to learn drops from six things to one. When the CRM changes how it paginates, one place needs fixing and nobody outside has to know.
So when working on site, before merging AI-generated code, count the public functions and ask which ones the client actually needs to call. Fold the rest inside.
Who is the tactical tornado on your team?
Ousterhout describes the tactical tornado as someone who does whatever it takes to push today’s progress forward, regardless of how much damage it does to the system. A summary of the book on freshman.tech notes that tactical programming is the default at most companies, aimed at getting features working as fast as possible.
Strategic programming, by contrast, is willing to spend time finding the best design that still works.
FDE work pushes you toward the tactical: the demo is next week, the client is waiting, and the agent writes code in seconds. When the tornado is an AI, you are the only strategic engineer left. One habit is easy to keep: after each session of AI code generation, set aside a short block purely for cleaning up the design, with no new features.
Comments are for whoever takes over
The third idea is short but valuable: comments should record what cannot be inferred from the code. What the client’s engineers need to know is the reasoning: why the connector skips records without an email address, which constraint from a legacy system forced this approach.
Those reasons live only in your head and in your meetings with the client. If they are not written down before handover day, they leave with you.
In what order should you read it?
If you are short of time, start with Software Engineering Radio episode 520 (July 12, 2022).
In it, Jeff Doolittle asks Ousterhout about complexity, modularity, layers, abstraction and information hiding. Next, listen to the April 2025 Pragmatic Engineer episode to hear how he sees AI coding, and only then read the book, prioritizing the sections on deep modules and comments.
If you have ever inherited someone else’s code, the book will put a name to exactly that pain, which is the reason to read it early. If you are new to the profession, do not skip the ideas that seem obvious: they are the first to be forgotten when a deadline closes in.
When you are job hunting, turn these ideas into evidence. In a CV or an FDE interview, describe a time you slimmed down a module’s interface before handover, and the client’s team was then able to make changes without calling you. A concrete story like that says far more than a generic line about “writing clean code.”
When Ousterhout talked about the tactical tornado on SE Radio in 2022, it was still a human programmer. Now it runs inside your IDE, and whether the handover is clean or tangled is up to whoever is at the wheel.
Was this article useful?
Thanks for the feedback!
5 sources
- A Philosophy of Software Design, 2nd Ed (Yaknyam Press ) · 2021-08-25
- John Ousterhout on A Philosophy of Software Design (Software Engineering Radio episode 520) · 2022-07-12
- Book Summary: A Philosophy of Software Design · 2021-06-15
- The Philosophy of Software Design – with John Ousterhout · 2025-04-09
- SE Radio 520: John Ousterhout on A Philosophy of Software Design · 2022-07-12