4 ms·

I don't really agree. Which is to say, good comments are helpful, but they are a flashlight in a dark room. If there's lots of furniture and clutter in the room

I don't really agree. Which is to say, good comments are helpful, but they are a flashlight in a dark room. If there's lots of furniture and clutter in the room, you still might trip over something. How many times in your codebase have you seen a comment like: // This exists because that dumb thing happened, // and during the migration from Y to Z we had to // support these two systems simultaneously. This // component mediates between the two . . . And someone had added some common logic into the mediator, then someone else had hooked into that, and now there's a snarl. The most important thing is that the system be as simple as it can while still performing its intended functions. We have all made a first cut at something that ended up being three times as verbose or complicated as our second. You want a system made out of pieces of the second kind. That's even more important than comments. I can definitely understand the desire to reduce lines of code, because it's often a good proxy for understanding how complicated a system is. Not always, but most of the time, something a quarter as long that does the same job is doing it a simpler way.

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.

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.