4 ms·

You should take the advice to mean "Don't comment on how your code is doing what it's doing, comment on why it's doing that." An English transliteration of a so

You should take the advice to mean "Don't comment on how your code is doing what it's doing, comment on why it's doing that." An English transliteration of a source code statement usually isn't very helpful.

mercer 11y ago
In general I agree with you, but specifically when using comments as headers, I think it's fine to describe briefly what it's doing (and how), in the same way that a header in a book often describes what the chapter is about.
- DougWebb 11y ago
  Sure, but a header in a book should just repeat the contents of the chapter but worded differently. In the same way, comments should not just reiterate the code. In the header case, the comment is a summary of what the code is doing, which I think is fine if it allows you to understand the code block quickly without reading it in detail. That's different from a comment like "Add one to index" followed by "index = index+1", which is the canonical/trivial example of what the advice is intended to recommend against.
  - Retra 11y ago
    Comments like "add one to index" are a symptom of laziness, not of commenting about the wrong thing. As an example, here is some of my actual code: /* Prompt for scheduler. */ if (!flag_scheduler_selected && !flag_no_prompts) { option_scheduler = prompt_scheduler(); } The purpose of the comment is not to tell you what it is doing or why I'm doing it. The comment is there to tell you that what I am doing now has nothing to do with what came before. It signals a mental context switch. Without the comment, you wouldn't be able to easily scan the code and see where different things are happening.
loco5niner 11y ago
Especially when the code is changed and the comment is now incorrect...
- talmand 11y ago
  The problem isn't the now incorrect comment, it is the person that didn't update the related comment.
- jdbernard 11y ago
  A wiki page/word doc is even easier to forget to update than in-line comments.
- dspillett 11y ago
  That is a "useful" code smell: if the code and the comments disagree, assume both are potentially wrong, handle with extreme care, and fix ASAP where possible.

mercer 11y ago

In general I agree with you, but specifically when using comments as headers, I think it's fine to describe briefly what it's doing (and how), in the same way that a header in a book often describes what the chapter is about.

DougWebb 11y ago
Sure, but a header in a book should just repeat the contents of the chapter but worded differently. In the same way, comments should not just reiterate the code. In the header case, the comment is a summary of what the code is doing, which I think is fine if it allows you to understand the code block quickly without reading it in detail. That's different from a comment like "Add one to index" followed by "index = index+1", which is the canonical/trivial example of what the advice is intended to recommend against.
- Retra 11y ago
  Comments like "add one to index" are a symptom of laziness, not of commenting about the wrong thing. As an example, here is some of my actual code: /* Prompt for scheduler. */ if (!flag_scheduler_selected && !flag_no_prompts) { option_scheduler = prompt_scheduler(); } The purpose of the comment is not to tell you what it is doing or why I'm doing it. The comment is there to tell you that what I am doing now has nothing to do with what came before. It signals a mental context switch. Without the comment, you wouldn't be able to easily scan the code and see where different things are happening.

loco5niner 11y ago

Especially when the code is changed and the comment is now incorrect...

talmand 11y ago
The problem isn't the now incorrect comment, it is the person that didn't update the related comment.
jdbernard 11y ago
A wiki page/word doc is even easier to forget to update than in-line comments.
dspillett 11y ago
That is a "useful" code smell: if the code and the comments disagree, assume both are potentially wrong, handle with extreme care, and fix ASAP where possible.