OK I GIVE UP
This short, easy-to-read, humble book contrasts greatly with most books on general programming topics. It does not treat the reader like a student, despite the author being a professor and the book being based on lecture notes and conversations with students. It does not claim to deliver the wisdom on how to build software, with a lot of condescending material on how it has always been done wrong, and all problems will vanish once the one way is followed. At the same time, it has a distinctive perspectve stated clearly, and offering concrete advice. This can be achieved only by someone who has done a lot of development themselves, and dealt with really complicated software that needs to promise a lot, and keep that promise.
And the author is exactly that kind of person. John Ousterhout is a professor of computer science at Stanford who designed Tcl and Tk, invented log-structured file systems, worked as a distinguished engineer at Sun Microsystems, and co-founded two software companies. He thus has both the theoretical and practical chops to comment on all things software development. This book is the outcome of course discussions with his students at Stanford and Ousterhout’s own insights about the practice of software design. What is the difference between software development and design? One could say that at the limit, software development is design, since it’s a purely mental process: The product of the design process is the end product. There is, however, a rather obviously separate process of designing a software system, evident from converstations about e.g. where a piece of data should go, or how the various components of a piece of software should be organized.
Ousterhout’s seed question is what should be the guiding principle of the design process to improve software development, so that writing software becomes easier, and we can build more powerful systems more cheaply. The one impeding factor that stops us from doing so is complexity, defined as “is anything that is related to the structure of a software system that makes it hard to understand and modify the system” (p. 5). This looks like a circular definition, since we target complexity because it makes software difficult to modify, but it’s defined as what makes software difficult to modify, but you should rather think of complexity as a kind of experience: It is not an inherent property of a system, but rather something developers face when trying to modify or understan it. This becomes more obvious when Ousterhout talks of the overall complexity of a system, which is “determined by the complexity of each part weighter by the fraction of time developers spend working on that part” (p. 6).
Defining complexity (and its opposite, simple) as an experience rather than an inherent property of a system has the quite useful advantage of precluding any useless arguing definitions and delineations; there is no need to argue whether X is simpler than Y, or whether e.g. easy and simple are the same thing. Instead, Ousterhout always hits the scale of “does this way of doing things make writing and understanding software easier”? This is a perfectly acceptable way of building a philosophy, namely a pragmatic one, and it leads to a book that’s simple itself, and hence short and concise.
The rest of the book is concerned about the nature of complexity, and how to avoid it. The three symptoms of complexity are the following:
Change amplification: Seemingly simple changes require modifications in many different code locations.
Cognitive load: Understanding one piece of logic requires referring to multiple separate locations, increasing the risk of bugs.
Unknown unknowns: It is not obvious which piece of code must be modified to complete a task.
Causes for complexity are put in two groups by Ousterhout: dependencies and obscurity. Dependency here is pretty much synonymous with coupling used in other texts: It’s very generally when a piece of code cannot be understood or modified in isolation. Obscurity is when important information is not obvious.
Designing software is an activity separate from coding itself, but it’s difficult to separate the two completely, as design is frequently done as a reaction to difficulties faced moving a codebase in a certain direction. As per the dictum “make the change easy, then make the easy change”, the best kind of design is done as a refactoring effort when the target functionality is too convoluted a change. You can alternatively do no design by just piling if-then-else’s and duplicated logic. Ousterhout distinguishes between tactical vs strategic programming to paint this divide. Tactical programming is when the only focus is to get something working without caring about complexity, hence introducing more and more of it into the codebase. Strategic programming, on the other hand, is where you “produce a great design, which also happens to work”. Without strategic programming, i.e. deliberate work to improve the design of the codebase and remove what is commonly termed technical debt, it is just a matter of time until development grinds to a halt due to the difficulty of introducing new functionality and how easy it is to introduce new bugs. Ousterhout even sets a number on how much strategic programming needs to be carried out: 10 to 20% of work effort should be put into it, so that the pace of development and the quality of the codebase stays at a certain level.
In the concluding chapters of the book, test-driven and agile development and their relationship to the tactical-vs-strategic divide is mentioned. The negative impact TDD can have on design is well-known and widely discussed. The extremely narrow focus on writing a failing test and making it pass can lead to an obsession with getting to working code to the detriment of all else. Ousterhout adds to this the psychological bias caused by a heavily tested codebase that one does not dare change the design of, lest hundreds if not thousands of tests are completely useless and need to be rewritten. His conclusion is that one should not put testing above good design, but keep automated testing as an integral part of software development.
Good design, as argued above, should help developers concentrate on what they are working on at a given point in time. The primary way of organizing code to enable this is modular design, i.e. decomposing code into independent units that interact through well-defined interfaces. A module here can be thought of generally, such as classes, namespaces or software packages. What makes a module good, that is, in which direction should we engineer it? Ousterout uses the relatively simple concept of depth to capture the essence of good modules. Depth refers to the amount of functionality a module hides behind its interface. Deep modules should be preferred to shallow ones, because the former make life easier for the user, taking away complexity and cognitive load for the user. Thinking of the amount of functionality in terms of depth, like a body of water, has the rather useful conceptual transfer that if you spread this functionality over a wider surface area, i.e. if you make the interface wider, you will end up making the module shallower, hence worse. This is an effect not many developers think about. Devs prefer to provide all kinds of arguments and configuration parameters to steer the inner workings of a module, thinking that this will make it more useful. The end result is the user of the module having to spend time reading the interface and documentation, deciphering the interaction of the various arguments, and figuring out which of the slightly different methods to use. When it comes to interfaces, less is more, and the strength of the abstraction a module provides derives from cohesion and simplicity. Ousterhout’s two examples for deep modules are extremely to the point. One is the file interface of Unix, where five methods that haven’t changed in a long time hide an immense amount of complexity. The second example is more unconventional because it’s not strictly a module: Garbage collection. It consists in the complete removal of a certain kind of interface (think ~malloc~) while providing a huge boon to the developer.
A significant part of the book is a discussion of how to achieve deep modules. Here is a list:
Information hiding: Hide implementation details and low-level workings behind the interface, so that the user does not have to care about them, and they can be changed independently. This is a lesson taught well in object-oriented design circles, but it also applies to bigger building blocks.
General purpose modules: This is a principle that Ousterhout derived from experience. A good way of creating a deep module is making the interface slightly more general to make it simpler. Otherwise the design is too coupled to the specifics of the first entry point, and will probably contain unnecessary details.
Different layers should provide different abstractions: In order for a layer of code (e.g. request handlers, service layer) to be worth keeping around, it should wrap some complexity, and hence present a different abstraction from other levels. A corollary of this (which took me a while to understand because I found it counter-intuitive) is that the level of abstraction within a module should be different from the interface. For instance, a method that accepts the ID of a domain object should internally work with business logic wrappers and not with the bare database rows, because that’s the level at which the abstraction works.
Pull complexity downwards: This is related to the previous point. Very generally, do not ask calling code to take care of complexity in order to make your own code simpler. Take away the thinking and the cognitive load. If your code does conversions to the layer at which it works, do those yourself, and do not ask the calling code. For instance, if any configuration parameters need to be set (chunk size for file reads or writes, network connection parameters etc.) your code should take care of these based on the environment instead of making them configuration parameters.
Split vs join: A frequent decision in programming is whether to keep pieces of logic together or split them into different components. The predominant logic in the “clean code” circles has been creating tiny classes for every bit of thing that can be named. Ousterhout opposes this without naming it, and advises against splitting things for the sake of it and creating incidental complexity. This is something I have done myself in the past because the conventional wisdom for a while was splitting classes or methods just because they are large. Such code frequently ends up being difficult to read, because quite a few variables have to be passed around as arguments and return values, necessitating jumping betwen locations to understand them.
Define errors out of existence: Understanding this one requires a proper change in perspective. The wisdom on error handling in the era of try/except’ing languages was that you should raise an exception when something bad happens and let the calling code handle it. Ousterhout argues that this is a bad idea, especially when overdone, because it’s the task of your code to deal with these exceptions, and the proper way to do this is, in the best case, not to cause an error at all. An example is getting the substring of a string by index, which causes an error in Java if the indexes are not within the bounds of the string, but is simply an empty string in Python.
After the rather enjoyable and engaging discussion of deep vs. shallow modules and how to achieve depth, the book veers away from software design, going more into general topics of programming, such as comments and naming. My initial reaction was to dismiss these chapters as mundane and out-of-place, but with Ousterhout having so much experience on demanding projects, it’s neigh impossible for him not to write wise things, and he always manages to touch on design. A significant part of the book (30 pages of 184 total) is dedicated to a detailed treatment of whether and how to write comments. When you engage with these chapters properly (or stay patient until the section titled “Comments are a design tool”), you recognize that what Ousterhout is addressing is not comments per se, but how to communicate the aspects of a piece of software not related to code. These are things such as the why of design, the counter-intuitive decisions which might have non-development related reasons, and comments that explain concepts from a different perspective as the code. Such comments help you improve and defend your design choices, much as good tests expose bad interfaces and design decisions.
The same perspective change applies to naming. Beyond the simple decisions like camel-case vs kebab-case or name vs noun, one should think of the act of naming as a way of interacting with the current design of the code: “If you find it difficult to come up with a name for a particular variable that is precise, intuitive, and not too long, this is a read flag. It suggests that the variable may not have a clear definition or purpose” (p. 126-127).
These positive remarks notwithstanding, I don’t think a section on using Javadoc and the like for organizing comments belongs in a book like this. Also, the advice that comments should describe every argument of a documented method is simply too much, and hence impractical.
Now to the elephant in the room: Does all of this matter in the age of AI? Do we even need to think about design, when we can simply prompt our favorite model to take care of design given a detailed problem description? I would love to be able to answer in the affirmative, and there are plenty of reasons for doing so. We still need to understand the consequences of our (or the models’) decisions, sometimes the correct design is not obvious, sometimes a bit more invention is needed. How much time will we dedicating to such discussion in the future? Will the software industry, in its current widely shared belief that AI does everything better (or at least faster), ever value talk about craft again? I highly doubt it.
That’s the negative side of the coin. The positive is that now you can be much more agressive with large-scale refactorings where tests need to be updated, or interface of a heavily used module is changed. LLMs are great with this kind of re-design, especially if you prompt them to actively ask questions, or if you give examples of what to do.
All programming requires is a creative mind and the ability to organize your thoughts. If you can visualize a system, you can probably implement it in a computer program (p. 1)
The overall idea behind comments is to capture information that was in the mind of the designer but couldn’t be represented in the code (p.95)
Structure software systems around the things that matter. For the things that don’t matter as much, try to minimize their impact on the rest of the system. (p. 171)
When choosing a name, the goal is to create an image in the mind of the reader about the nature of the thing being named. (p. 122)
Comments serve as a canary in the coal mine of complexity. If a method or variable requires a long comment, it is a red flag that you don’t have a good abstraction. (p. 133)