DEV Community

Cover image for 5 clean code techniques you can start doing today

5 clean code techniques you can start doing today

Patricio Ferraggi on March 09, 2020

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...
Collapse
 
marcingolenia profile image
marcingolenia • Edited

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:

Collapse
 
codemouse92 profile image
Jason C. McDonald • Edited

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 • Edited

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 • Edited

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 • Edited

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 • Edited

That's when we enforce intent comment.

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


Collapse
 
jdforsythe profile image
Jeremy Forsythe

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.

Collapse
 
patferraggi profile image
Patricio Ferraggi • Edited

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

Collapse
 
nathanoleach profile image
Nathan Leach • Edited

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.

Collapse
 
deadlysilent1 profile image
Troy Jordan

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.

Collapse
 
patferraggi profile image
Patricio Ferraggi

Been there, done that my friend ahaha 😃