3 ms·
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
by 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 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.