John Ousterhout’s A Philosophy Of Software Design is one of my favourite software design books.
Very short, well-articulated and pragmatic, Ousterhout manages to explain the rationale behind many practices we usually learn with experience, yet are often not able to articulate clearly.
I’ll write a new, complete, review of the book one day to replace the private one I wrote and lost...
but in the meantime, some recent discussions made me realize that the few red flags John Ousterhout scatters throughout the book are very valuable nuggets, which convey a lot of important ideas in very few sentences.
And since the book is only available in a paper edition, I usually have a hard time sharing them with friends and colleagues.
Without further ado, here are all the Software Design Red Flags from A Philosophy of Software Design.
I hope this little glimpse will be the nudge you need to get your own copy of the book, and that you will enjoy it as much as I did.
Shallow Module (chapter 4.6)
A shallow module is one whose interface is complicated relative to the functionality it provides.
Shallow modules don’t help much in the battle against complexity, because the benefit they provide (not having to learn about how they work internally) is negated by the cost of learning and using their interfaces. Small modules tend to be shallow.
Information leakage (chapter 5.2)
Information leakage occurs when the same knowledge is used in multiple places, such as two different classes that both understand the format of a particular type of file.
Temporal decomposition (chapter 5.3)
In temporal decomposition, execution order is reflected in the code structure: operations that happen at different times are in different methods or classes.
If the same knowledge is used at different point in execution, it gets encoded in multiple places, resulting in information leakage.
Overexposure (chapter 5.7)
If the API for a commonly used feature forces users to learn about other features that are rarely used, this increases the cognitive load on users who don’t need the rarely used features.
Pass-Through Method (chapter 7.1)
A pass-through method is one that does nothing except pass its arguments to another method, usually with the same API as the pass through method.
This typically indicates that there is not a clean division of responsibility between the classes.
Repetition (chapter 9.4)
If the same piece of code (or code that is almost the same) appears over and over again, that’s a red flag that you haven’t found the right abstractions.
Special-General Mixture (chapter 9.5)
This red flag occurs when a general-purpose mechanism also contains code specialized for a particular use of that mechanism.
This makes the mechanism more complicated and creates information leakage between the mechanism and the particular use case:
future modifications to the use case are likely to require changes to the underlying mechanism as well.
Conjoined Methods (chapter 9.8)
It should be possible to understand each method independently.
If you can't understand the implementation of method without also understanding the implementation of another, that's a red flag.
This red flag can occur in other contexts as well: if two pieces of code are physically separated, but each can only be understood by looking at the other, that is a red flag.
Comment Repeats Code (chapter 13.2)
If the information in a comment is already obvious from the code next to the comment, then the comment isn’t helpful.
One example of this is when the comment uses the same words that make up the name of the thing it is describing.Implementation Documentation Contaminates Interface (chapter 13.5)
This red flag occurs when interface documentation, such as that for a method, describes implementation details that aren’t needed in order to use the thing being documented.
Vague Name (chapter 14.3)
If a variable or method name is broad enough to refer to many different things, then it doesn’t convey much information to the developer and the underlying entity is more likely to be misused.
Hard to Pick Name (chapter 14.3)
If it’s hard to find a simple name for a variable or method that creates a clear image of the underlying object, that’s a hint that the underlying object may not have a clean design.
Hard to Describe (chapter 15.3)
The comment that describes a method or variable should be simple and yet complete.
If you find it difficult to write such a comment, that’s an indicator that there might be a problem with the design of the thing you are describing.
Nonobvious Code (chapter 18.2)
If the meaning and behavior of code cannot be understood with a quick reading, it is a red flag.
Often this means that there is important information that is not immediately clear to someone reading the code.
To be continued with a full review of the book... soon.
banner: my own copy. Obviously, a few sections caught my attention
Originally published on notes.portebois.net
Top comments (0)