3 ms·

I find that the commonly touted opinion that comments should only reflect why, and avoid all duplication; is misguided. The only places where I will elaborate o

I find that the commonly touted opinion that comments should only reflect why, and avoid all duplication; is misguided. The only places where I will elaborate on why is where I can see obvious room for improvement but I'm still waiting for the bigger picture to stabilize, or I'm adding a dependency that I'm not really happy with. Otherwise my comments mostly express the intent of the code in regular prose and have to be updated with the code.

RangerScience 10y ago
I'd say then that your comments [regarding intent] are overly specific. If updating the code block results in code with a different intent... you're not updating it, you're replacing it, and should take out the original comment with the original code. If I have a code block to maintain data synchronization with a a server - that's the intent; if the code is updated from long-polling to websockets, the intent hasn't changed.
gnaritas 10y ago
If your comments just say what the code does, they're redundant and unnecessary. Good comments explain things the code can't, like why you chose a particular algo, or why some piece of code needs to exist. Most code when written well requires no comments. Comments like yours, that repeat what the code does, I simply delete.
- codr4life 10y ago
  Like I said, I don't agree with that particular broken record; there is value in stating the intent of code in normal prose as documentation.
  - gnaritas 10y ago
    Yes there is value, comments like those let me know which developers need more training to learn how to code cleaner. I know what you said, and I disagreed; responding back by repeating your disagreement doesn't add any value to the conversation.
jhlgkhkhil 10y ago
So they quickly fall out of sync with the code and cause more problems than they solve.. Clearly written code already expresses what it does unambiguously. If your code doesn't do what it is supposed to do that is a bigger problem.

RangerScience 10y ago

I'd say then that your comments [regarding intent] are overly specific. If updating the code block results in code with a different intent... you're not updating it, you're replacing it, and should take out the original comment with the original code. If I have a code block to maintain data synchronization with a a server - that's the intent; if the code is updated from long-polling to websockets, the intent hasn't changed.

gnaritas 10y ago

If your comments just say what the code does, they're redundant and unnecessary. Good comments explain things the code can't, like why you chose a particular algo, or why some piece of code needs to exist. Most code when written well requires no comments. Comments like yours, that repeat what the code does, I simply delete.

codr4life 10y ago
Like I said, I don't agree with that particular broken record; there is value in stating the intent of code in normal prose as documentation.
- gnaritas 10y ago
  Yes there is value, comments like those let me know which developers need more training to learn how to code cleaner. I know what you said, and I disagreed; responding back by repeating your disagreement doesn't add any value to the conversation.

jhlgkhkhil 10y ago

So they quickly fall out of sync with the code and cause more problems than they solve.. Clearly written code already expresses what it does unambiguously. If your code doesn't do what it is supposed to do that is a bigger problem.