Re:How important is it to reduce the number of lines in code?
by jamesaguilar on Sunday April 07, 2013 @09:54PM
(#5509591)
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.
Re:How important is it to reduce the number of lines in code?
by timr on Friday April 12, 2013 @09:39PM
(#5542178)
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.
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.