Ousterhout puts an emphasis on writing good comments as part of the software's documentation. He sees the avoidance of writing comments (such as promoted by Uncle Bob and others) as excuses. According to him, the four excuses are: 1. "Good Code is self-documenting". This implies that the user of an interface must read its implementation, which destroys the idea of abstracting the implementation behind the interface of a function 2. "I don't have time to write comments". Having a good documentation will save more development time in the future than it costs to do the documentation 3. "Comments get out of date and become misleading". This doesn't happen frequently, only at places where code is fundamentally changed often (which in itself is a red flag) 4. "All the comments I have seen are worthless". - [[Argumentation Fallacies#Hasty Generalization]] Ousterhout does not accept those excuses and instead provides a framework to use comments for a code documentation of high quality. Personally, I have been at many points where the code wasn't obvious, and comments would have helped, because the code itself doesn't convey as much information as is needed to understand it, especially in the context of the higher level usage. Most code can be broken down a la clean code to create a bunch of functions that are so short that they wouldn't need comments (which creates a debatable amount of functions per interface), but even then it will not tell you how to use it, when to use it, what exception can appear, what invariants need to be considered for input parameters, etc. Comments can also help to understand highly difficult pieces of code, which simply can't be simplified due to the nature of the algorithm or data structures. **Summary** - Avoiding to write comments is based on 4 major assumptions - Comments can help to understand the interface of a module or function better, which is why we should write high quality comments - Personal Experience supports this philosophy - code is not always enough to convey everything a programmer was imagining when writing it # References John Ousterhout - A Philosophy of Software Design – Chapter 12