Beyond "Clean Code": Why Your Comments Matter

blinkbat

I disagree that it's the codebase's job to communicate product's intent

johnmwilkinson

I completely agree. I wrote a book on the subject of how to write clear code (Bob Martin was off by one letter!) and comments are a key element of that. https://elementsofcode.io/chapters/documentation/ We’re in good company: Jon Ousterhaut had a conversation with Uncle Bob where he brings up the exact passage you quote as a point of disagreement.

magicalhippo

I reached the same conclusion. Yes, absolutely let the code be self-documenting by structuring it well, using well-named functions and variables and so on. This will make it clear what you're trying to do. So yes, you shouldn't write "check if greater than two" in a comment, that should be obvious from the code itself. But sometimes the why is very important, and it is not readily obvious from the what . Ideally try to modify the code so it becomes clear. Don't just check against two, check against a named constant that provides information through the name. However what can be more difficult to express cleanly is for example why the check is being done here and not somewhere else, in the cases where that matters. In those cases, help the reader by adding some clarifying comments as to why this is being done.