Talk:Comment Only What the Code Cannot Say
From Programmer 97-things
One way to read "comment only what the code cannot say" is that you can write code that is self documenting.
My personal convention is to include enough comments so that someone else could re-write the code using only the comments. The crux of the article implies that this convention results in "noisy" comments serve no purpose.
I believe that good comments provide an extra dimension that code itself cannot: intent (what a block of code intends to do vs. what it is doing). Of course, one could argue that if a block of code has a bug, adding a comment that simply parrots that bug does not buy you anything. The trick, which one could argue a "correct" reading of the article actually says, is to document code using good comments.
In addition to providing the reader with the intent of a block of code, the very act of writing good comments serves as a self-code review. I've caught many bugs as I was commenting code and realizing that the code didn't actually do what I was documenting it did.
In my experience in maintaining existing code bases, I have faced the problem of too little or no comments far more often than I have faced the problem of too many comments. Given the choice, I'll choose the latter every time.
My experiences have perhaps been a little different and have been based on a large cross-section of code written in a variety of languages, with some code dating back decades and some code as fresh as the New Year (and yet aspiring to legacy from the moment it was written). People often write comments with the best of intentions, but this is where they often become unstuck. Their comments are surprisingly useless in many cases, and are most often a salve for questionable code.
The first thing to do is perhaps to question the assume that comments should allow someone else to rewrite the code from scratch. Why would this be useful? The idea that this is would be useful masks a deeper issue: What is wrong with the code itself that it needs such a form of detailed explanation? Instead of investing time in writing comments that compensate for poor code, that energy should be directed into improving the code. Rather than offering explanations of code elements, the author of the code needs to ask whether there is a way of rephrasing the code that makes the comment simpler or superfluous. This would be time far more wisely spent.
The other subtle fallacy hidden here is that someone who is not able to express themselves clearly in code is able to do so in comments. While it does not necessarily follow that someone who cannot express themselves clearly in code is unable to do so in natural language, most of the comments I have ever read suggest that these are not entirely uncorrelated (and even the inverse correlation may exist). Reading rambling, ill-considered comments that are either misleading because they have the wrong emphasis or simply because they are wrong is one of the classic time wasters of heavily commented code. These comments do not provide the reader with a useful guide. And they certainly wouldn't allow anyone to rewrite the code from scratch. And yet such form the silent majority of comments that people don't want to talk about when they advocate a heavy commenting style. Removing such comments often allows you to focus on the code more clearly, to work backwards to what may have been intended.
This point of view does not, of course, suggest that all comments are unnecessary or superfluous... just the unnecessary and superfluous ones. Which is most of them. Of course, who is to say that code is self-documenting? Not the self who wrote them. This is where code reviews and pairing can help. They can also help with uncovering bugs, as can tests. Writing documentation at a higher level for the code can also help to clarify oversights and mistakes in the code. Importantly, in each of these cases, the insight comes from working from a different point of view.
If your code already says something clearly, there is no need to write a comment. Given the choice, Comment Only What the Code Cannot Say!
