3 ms·
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 t
by 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 agoSure, 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 agoComments 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.