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.
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.
Thanks for your feedback. (I am the author of that article.) I was trying to argue that it’s the code’s job to communicate its authors’ intent for the code itself. To help me clarify my writing, can you tell me what I wrote that led you believe I was talking about intent at the product level and not the code level? Thanks!
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.
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.
I disagree that it's the codebase's job to communicate product's intent
Thanks for your feedback. (I am the author of that article.) I was trying to argue that it’s the code’s job to communicate its authors’ intent for the code itself. To help me clarify my writing, can you tell me what I wrote that led you believe I was talking about intent at the product level and not the code level? Thanks!