I heard you out, but I still disagree with your stance on comments. The entire case falls apart if comments are dedicated solely to the one thing they're appropriate for: stating intention. The cleanest code in the world is not going to tell you anything about what the programmer meant to do.
Everything you said is true of comments that restate code, and there is certainly no excuse for those sorts of comments. But just because polka is annoying doesn't mean we burn all the accordions.
(And yes, I've used intent-commenting for years with my team; the short- and long-term benefits greatly outweigh the effort involved every time.)
I've also noticed that intent comments doesn't get stale like bad comments, intent comments are tied to the purpose/objective instead to code, is not rare that a piece of code change but not that it's purpose change.
Maybe that's a sign of a useful comment, one that shouldn't get obsolete with an implementation change.
I am a self-taught developer from Argentina currently living in Spain. I am passionate about improving my technical skills and helping others do the same.
I am not sure about this one, I have seen comments get stale even if they are the "good comments", I have seen comments trying to convey intent on code that doesn't exist anymore, it was the intent for a class that it was deleted ages ago. Maybe I had some bad experiences and this is not the norm.
The only reason it gets stale is if you let it. I hear the "out of sync" argument a lot, but that problem is just as common with descriptive names! Yet I don't see any articles decrying descriptive naming as a result: you update the name.
Keep your comments in sync as a mandatory part of refactoring. Get into the habit of distrusting any code with a mismatching intent comment; it usually means both code and comment are wrong.
I am a self-taught developer from Argentina currently living in Spain. I am passionate about improving my technical skills and helping others do the same.
I do agree with you, maybe the rule should be then, only write comments to provide intent? unfortunately, this reason is not the main reason people use comments, at least not in experience. People tend to use comments to restate code or explain bad implementations, intention comments are just a small part of that.
I feel like it is another exception, and not something big enough to change a rule.
I heard you out, but I still disagree with your stance on comments. The entire case falls apart if comments are dedicated solely to the one thing they're appropriate for: stating intention. The cleanest code in the world is not going to tell you anything about what the programmer meant to do.
Everything you said is true of comments that restate code, and there is certainly no excuse for those sorts of comments. But just because polka is annoying doesn't mean we burn all the accordions.
(And yes, I've used intent-commenting for years with my team; the short- and long-term benefits greatly outweigh the effort involved every time.)
I've also noticed that intent comments doesn't get stale like bad comments, intent comments are tied to the purpose/objective instead to code, is not rare that a piece of code change but not that it's purpose change.
Maybe that's a sign of a useful comment, one that shouldn't get obsolete with an implementation change.
I am not sure about this one, I have seen comments get stale even if they are the "good comments", I have seen comments trying to convey intent on code that doesn't exist anymore, it was the intent for a class that it was deleted ages ago. Maybe I had some bad experiences and this is not the norm.
The only reason it gets stale is if you let it. I hear the "out of sync" argument a lot, but that problem is just as common with descriptive names! Yet I don't see any articles decrying descriptive naming as a result: you update the name.
Keep your comments in sync as a mandatory part of refactoring. Get into the habit of distrusting any code with a mismatching intent comment; it usually means both code and comment are wrong.
If your comments usually get out of sync, then it could be a symptom your code review process needs to be improved.
I do agree with you, maybe the rule should be then, only write comments to provide intent? unfortunately, this reason is not the main reason people use comments, at least not in experience. People tend to use comments to restate code or explain bad implementations, intention comments are just a small part of that.
I feel like it is another exception, and not something big enough to change a rule.
That's when we enforce intent comment.
People abuse lambdas, but I don't hear any calls to eschew them from code.
To Comment Or Not To Comment?
Jason C. McDonald ・ Jan 20 '19 ・ 12 min read