Hacker News new | ask | show | jobs
by _ZeD_ 2413 days ago
(not OP, but here's my 2c) comments should explain why you choose to write the corresponding line of code. It's a "meta-communication" between the original author (even a previous-month you) and the reader. Code reading should be "boring". The code lines (and so the meaning) should be obvious. A good comment, IMHO, should convey the information "I'm sorry for this complexity here, but you need to take care of this edge case..."
1 comments

That's a reasonable attempt at defining what over-commenting is by trying to define what it isn't. However, it's not a very subjective definition. I tend to write fairly long comments anywhere I think it might help me in the future. I can't predict what I'll forget. I can't predict what will help me understand my code in the future. I have almost never looked at a comment and wished that someone would have written less (aside from comments that just mimic the code, e.g. "increment x"). It's almost always the opposite. I almost always wish I (or the other dev) had left more information.

Literate programming comes to mind as an extreme counter example of not enough comments. https://en.wikipedia.org/wiki/Donald_Knuth#Literate_programm...