Book Review: A Philosophy of Software Design

TLDR

This book is a great read and quite remarkable in its brevity.

The author made multiple insightful points; I found myself nodding vigorously in agreement with the numerous insightful gems spread across the book.

Ultimately, the book’s core thesis is minimizing complexity in software development by adopting complexity-eliminating approaches. The upfront investment in learning and adopting better designs pays off because it leads to high-quality software.

Things I like about the book

Short and sweet: Concise with little cruft.
Clarity: Expressive terminology, examples, and diagrams for succinctly conveying complex concepts; lucid diagrams simplified the explanation of complicated sections like pass-through methods and shared variables.

Things that could be better

More examples: having a wide variety of real-life examples from multiple projects would have helped.
Broader scope: The book does not discuss other aspects of software development: testing, reviews, release agility, etc.

Who should read this book?

I recommend this book to software engineers and line managers because of its tactical focus and valuable advice. I do not think upper-level managers would find it very useful since they are usually farther away from low-level details.

Get the book from Amazon here.

Chapter Notes

Chapter 4: Modules Should Be Deep

The best modules have interfaces that are simpler than their implementations.
The safest interfaces are fully explicit; module specifications should contain all the information a developer needs. Implicit interface aspects lead to tribal knowledge, especially since these esoteric details can’t be checked by tools, compilers, or programming languages.
Prioritize the most common use cases during design and provide specialized handling for non-common scenarios.

Chapter 7: Different Layer, Different Abstraction

A pass-through method does nothing except pass its arguments to another method. Having multiple functions with the same signature typically indicates a design smell (there is not a clean separation of responsibility between classes).
- Notes: This resonated because I have committed this design flaw in the past; pass-through methods are challenging to debug and understand.
The interface to some piece of functionality should be in the same class that implements the functionality.
Pass-through variables are tougher to handle – using a shared context is a great way to avoid this.

Chapter 10: Define errors out of existence

Exceptions breed more exceptions; for example, retries can necessitate more code to handle new conditions, e.g., thundering herds, duplicate messages, and rate-limiting. It is also tricky to replicate certain exceptions in test environments, e.g., IOExceptions.
Throwing exceptions is easy; handling them is hard. If you are having difficulty figuring out how to handle a case, punting that decision to callers is also suboptimal since they probably will find it doubly tricky too.
Exceptions lead to complex interfaces; some argue that defining errors out of existence will miss out on catching bugs; the counterargument is that handling exceptions necessitates writing more code to handle such exceptions. Given the complexity of software, less is more, simple > complex. More code, more bugs.
I like RAMCloud’s approach of crashing a server whenever a corrupt object is discovered. This technique significantly increases the recovery cost; however, simplification and frequent code execution benefits make up for that cost.

Chapter 11: Design it Twice

Having at least two designs before implementation leads to better architecture – allows for objectively comparing and contrasting approaches.
Maintaining well-designed software is cheaper than reworking poor architectural choices.

Chapter 12: Why Write Comments? The Four Excuses

I like his approach of estimating how much time engineers spend writing code (versus designing, reviewing, compiling, testing, etc.) and using that to set an upper bound for writing documentation.
Overall, this chapter felt light on detailed examples.

Chapter 13: Comments Should Describe Things that aren’t obvious from the code

Cross-module documentation wherein updating a single file (e.g., adding a new status code) leads to multiple changes across multiple files. The suboptimal but widespread solution for this ubiquitous challenge is to consult the experts and leverage their tribal knowledge. I love his recommendation of using comments to signal what files to change; this empowers the entire team and reduces cognitive overload.
Don’t Repeat Yourself (DRY) applies to documentation, especially for scenarios involving disparate files. Consider creating a central file to hold all the details and referring to that file from consuming locations.
I can’t entirely agree with the pedantic approach to over-commenting everything. Comments are not an end to themselves; instead, they serve to cognitive overload.
Examples from RAMCloud dominated the chapter; a variety of samples would have been more useful.

Chapter 14: Choosing Names

Poor naming compounds negatively since software projects have thousands of variable, method, and class names. A single lousy name has a limited impact; however, many bad labels will lead to obscurity and increase complexity.
Names are abstractions; thus, great names are precise, unambiguous, and intuitive.
If you struggle to name a variable, that might indicate underlying design issues.
Consistency in naming: if it looks like a duck, swims like a duck, and quacks like a duck, then it better be is a duck.

Chapter 15: Write The Comments First

Putting off documentation as the last thing in the development process leads to poor quality docs; frontload it and do it first.
Struggling to document a method or class might indicate poor design.

Chapter 16: Modifying Existing Code

If you are not making the overall system design better with each change, you are probably making it worse. Entropy is the default state of systems.
I disagree that keeping comments next to code mitigates the code rot problem fully. It ameliorates it but does not solve it significantly.
I like the heuristic: the farther away a comment block is from its implementation, the more abstract it should be
DRY applies to comments and documentation too! The author breaks the rule by regurgitating some past work in this section.

Chapter 17: Consistency

Consistency reduces cognitive overload; it creates mental leverage because developers can pattern-match. Naming and coding conventions help (as well as a healthy dose of nit-picky code reviews and documenting team engineering expectations).
Rarely introduce new styles – the disruptive cost of losing consistency rarely justifies the price. Stick with established styles even if they are not the most perfect.

Chapter 18: Code Should be Obvious

Obscure code requires a lot of time and energy to understand and raises the chances of bugs and misunderstandings. The long-term cost of maintenance outweighs any short-term benefits to the code author.
C# tuples and Java Pairs return multiple values from a method but increase obscurity, especially since their extractors are generic (e.g., getValue, getKey). It is better to introduce new strongly-typed types that eliminate all ambiguity.
I do not fully agree with the recommendation to always use the same types for allocation and declaration. While I agree with the obscurity; I think using interfaces helps with deeper modules; a good example is using IEnumerable in method signatures but casting it to a List in the method body.

Chapter 19: Software Trends

The author posits that TDD focuses on getting features working (tactical) at the expense of finding the best design (strategic).
I like his perspective that getters/setters mostly add clutter.
Whenever a new software development paradigm pops up, challenge it; does it minimize complexity? Think about obscurity, complexity, cognitive overload, bloat, etc.

Chapter 20: Performance

This chapter read like a tack-on to meet book-length requirements.
Examples of expensive calls:
- A round trip network call within a data center can take 10 – 50μs (which is 10k x instruction times)
- I/O to secondary storage (disks) can take 5 – 10ms (millions of instructions time); newer storage can be as fast as 1μs (which is about 2k instruction times).
Performance might not be essential for special cases, so ensure the critical path is clear and handle edge cases with simplicity.