Hacker News Reader

Comment by codr4life | Hacker News Reader

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.

View on HN

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.

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.

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.

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.

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.

Reply on news.ycombinator.com