DEV Community

loading...

Discussion on: 5 clean code techniques you can start doing today

Collapse
codemouse92 profile image
Jason C. McDonald

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.)

Collapse
ghost profile image
Ghost

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.

Collapse
patferraggi profile image
Patricio Ferraggi Author

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.

Thread Thread
codemouse92 profile image
Jason C. McDonald

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.

Thread Thread
acostalima profile image
André Costa Lima

If your comments usually get out of sync, then it could be a symptom your code review process needs to be improved.

Collapse
patferraggi profile image
Patricio Ferraggi Author

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.

Collapse
codemouse92 profile image
Jason C. McDonald

That's when we enforce intent comment.

People abuse lambdas, but I don't hear any calls to eschew them from code.