A Philosophy of Software Design

by John Ousterhout

Instead of writing a comment to explain what is happening in a block of code in a method, Martin suggests pulling that block out into a separate method (with no comments) and using the name of the method as a replacement for the comment. This results in long names such as isLeastRelevantMultipleOfNextLargerPrimeFactor. Even with all these words, names like this are cryptic and provide less information than a well-written comment. And, with this approach, developers end up effectively retyping the documentation for a method every time they invoke it! I worry that Martin’s philosophy encourages a bad attitude in programmers, where they avoid comments so as not to seem like failures. This could even result in good designers coming under false criticism: “What’s wrong with your code that it requires comments?” Well-written comments are not failures. They increase the value of code and serve a fundamental role in defining abstractions and managing system complexity.