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.
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.
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.
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.
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.
