2 ms·

That's an easy question: it almost never happens. The most frequent occurrence (by far) is that there are no comments at all, just a wall of indecipherable co

by timr 14y ago

That's an easy question: it almost never happens. The most frequent occurrence (by far) is that there are no comments at all, just a wall of indecipherable code. Even an old comment describing intent and usage is better than no comments at all. In your example, even if that comment is outdated, it's still incredibly useful. It tells you, in under 5 seconds, the original intent of a piece of code, and how it was supposed to fit into the entire system. That's something you'll never get without a comprehensive understanding of the project, which takes far more than 5 seconds of reading. The real problem here is not that there is a comment -- the problem is that a bad coder fucked up by not updating the comment. There's no excuse. That all of the commenters below will spend paragraphs explaining how they shouldn't have to document their code with the occasional descriptive comment is an amazing testament to the overwhelming power of human laziness and self-delusion.

jamesaguilar 14y ago
My point is not that this comment is unhelpful. My point is that it would be better if the reason for this comment's existence were eliminated. I.e. that the removal of unnecessary complication in the system is an even more laudable goal than commenting well. Obviously, both will have a part in any well written an maintained system. But the person I'm responding to held good comments up as the most important aspect of system maintainability, and that is simply not the case.
- timr 14y ago
  You were responding to me, and no, that's not what I meant. ;-) I'm not saying that comments are the "most important" aspect of system maintainability, but that they're one of a few things that are all of top importance. Obviously, if you write spaghetti code, your system won't be maintainable, no matter how many comments you write. But that's a false dichotomy: you need to write good code and you need to write good comments. Neglecting either one leads to unmaintainable systems.

by timr 14y ago

jamesaguilar 14y ago

My point is not that this comment is unhelpful. My point is that it would be better if the reason for this comment's existence were eliminated. I.e. that the removal of unnecessary complication in the system is an even more laudable goal than commenting well. Obviously, both will have a part in any well written an maintained system. But the person I'm responding to held good comments up as the most important aspect of system maintainability, and that is simply not the case.

timr 14y ago
You were responding to me, and no, that's not what I meant. ;-) I'm not saying that comments are the "most important" aspect of system maintainability, but that they're one of a few things that are all of top importance. Obviously, if you write spaghetti code, your system won't be maintainable, no matter how many comments you write. But that's a false dichotomy: you need to write good code and you need to write good comments. Neglecting either one leads to unmaintainable systems.