If you are interested in reading this article in Spanish, check out my blog The Developer's Dungeon
Two years ago I started looking for ways to im...
For further actions, you may consider blocking this person and/or reporting abuse
Regarding comments. 100% agree with Patricio. More over - Gentleman's! The case has been closed for 12 years! Rober C. Martin made it clear in his book - clean code. The code should be self-documenting. This means that "no comment" should be the default - if necessary add the comment to express your intent or if you need additional license info to a script file (for projects you can include it in assembly info). But this is rather an exception, not a practice. The intent of the developer if it cannot be included in variable name, method name (in most cases it can) then there is a far better way of documenting the code than a comment which WILL (sooner or later) become falsy - write test that explains the intent. Also, take a look on Mark Seeman tweet:
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
I disagree with your stance on comments a bit. I agree that comments should not be explaining what the code is doing (unless it's really necessary to write some hard to grok code for the sake of performance). However, comments are useful in explaining one thing that code alone cannot - why you did something.
One example - If you made a decision based on tradeoffs, especially if it's not the obvious choice, and you need to relate to the next dev that they shouldn't refactor it to the "obvious" choice, comments are a great way to keep that note right by the code.
But mostly I agree that code should be clear enough that you shouldn't have comments explaining what your code is doing.
Hey Jeremy, thank you for commenting. I have to agree with you on that regard, that one is a good example of a valid comment I did not thought off, but wouldn't you say that it would fit better on my small list of exceptions instead of a common rule? I still think that in general you have more reasons to avoid comments than to use them. Unfortunately most of the comments we see in code could be very well explained with proper naming and correct use of abstractions
While they can certainly be misused, the best, legitimate use of comments is likely to state the "why" of a solution...the business rules or decision points...something that is rarely, if ever, explained by the code itself. It's the question that the person maintaining your code will ask themselves over and over again. So, do them a favor...and explicitly answer it, proactively.
I often find myself writing comments for a line of code which is self explanatory and wondered why I bother writing the comment in the first place.
Been there, done that my friend ahaha 😃