Book Recommendation: A Philosophy Of Software Design

This is a book that I would recommend every 6+ month experienced software engineer to read (which is most software engineers). It does not involve too much processing to understand topics being discussed. I will try to note my biggest takeaways which means this is not a summary of the book nor a review. The author is John Ousterhout with an ISBN number of 978-1-7321022-0-0.

Usually books get dry beyond the first few chapters despite the potentially useful information present. This one is different, it presents topics less discussed as part of developing one’s software engineering self. It steps back to the fundamental building blocks that contribute to good software.

It starts off with defining complexity and what constitutes it. Interestingly, most people would think that complexity is hard but the author argues that it depends on the use of that complexity and how it is deployed. He dives into things that constitute complexity such as unknown unknowns which are the worst kind, he gives insights into how to deal with it. An unknown could be as simple as changing the colour of the background, could that trigger an unintended change somewhere else without knowing upfront.

After complexity, it becomes around modules. What is a module you might say? It is something you can interact with using an interface, an example is a function/class. He stresses the importance of taking the time to think about interfaces of modules when designing code. The simpler the interface the less work the user would have to do to use. Though it shouldn’t be too simple in the sense that the module is doing what can be done in a few lines outright.

Building up on modules, the concept of shallow and deep modules gets into view. A shallow module is one where in order to use it you would have to write some boilerplate code, read implementation and dig deep into the code. Whereas a deeper module is one where you can use without worrying about how it is implemented, it just works.

On top of that, modules tend to cause pain in the long term if you’re in a hurry designing them. This is where documentation comes in. The same way some people refer to test driven development, the author is an advocate of writing user facing documentation first before cracking into implementation details. It is quite a shocking thing to read but makes a lot of sense. Despite all the worries of documentation going stale, too detailed or too verbose, a well documented module interface is one where implementation is hidden and just fits into place without any development frustration.

Naming was another thing the book got into, ideally names should make you imagine what’s happening. A well named variable contributes to good documentation. Rarely does badly named code make sense and it should never be excusable to name something badly. Only attach a comment to a variable that’s hard to figure out name off but try your best to keep it simple. At the end of the day, the reader of your code is likely going to be a user at some point especially if the code is general purpose enough.

Circling back to modules, all abstractions at some point leak. A leak is when information of/for implementation gets out. This is where coupling comes into place, a deep module is better than 3 shallower ones if they all can only be used together. Try to maintain that thought when designing code. Alternatively, do leak information if it is absolutely necessary for the user to know, it just becomes part of the well documented and easy interface. It goes without saying that the design of a module is context dependent but that should never mean to assume the user of your module is aware of the full context. That’s why try to group similar things together if not combined.

A lot gets covered in this book. It is quite remarkable how much goes on in designing software. There is a lot of examples mentioned during the flow of reading the book that would make you stop and think about things differently. The book doesn’t get into automated testing as much and thats something I wished more of but nonetheless it is a great short and thought provoking read that I encourage people to read.