DEV Community

Cover image for Code Comments Are Not Evil

Code Comments Are Not Evil

Grant Riordan on July 24, 2024

Code should be self-documenting, there’s no need for comments. As a developer, you’ll have heard someone in your team say this phrase at one poi...
Read full post
Collapse
 
darkwiiplayer profile image
𒎏Wii 🏳️‍⚧️ • • Edited 
user.discount = 0.2; // Premium members get a 20% discount
Enter fullscreen mode Exit fullscreen mode 
// Add a to b
return a + b;
Enter fullscreen mode Exit fullscreen mode

I honestly don't see any difference between these two. They both simply spell out the code in prose without adding any additional information.

The only difference I see is that the first bit of code seems like the user discount should be extracted into a configuration source rather than hard-coded like that.

Meanwhile, an example like this:

const calculateTotal = (cart: Item[]): number => {
    //Temp Hotifx: Use 0 as the default price for items with undefined prices
    return cart.reduce((total, item) => total + (item.price ?? 0), 0);
}
Enter fullscreen mode Exit fullscreen mode

Is ironically a situation where I would use a comment, but the example once again just spells out the code.

I read the code and notice 0 is used as the fallback price. I wonder how that could make sense and read the comment for more context only to find... what I already knew.

A better comment would have been:

// hotfix: import error caused price on free items to be NULL;
// this doesn't otherwise happen so these prices can always be
// treated as 0
Enter fullscreen mode Exit fullscreen mode

Now I read the code and know that it makes sense and isn't an error, and that somebody (maybe even past me) has already confirmed those things. It also gives me a lot more context regarding whether it might be time to remove this hotfix or it is still necessary: Since it was a one-off import error, I can check the database for NULL prices and if they've been fixed, remove the code.

And lastly:

Avoid using humorous comments in your code. While they might be entertaining, they are unprofessional and take up valuable space.

Nah, a bit of humour isn't unprofessional. Just avoid jokes that you wouldn't be comfortable telling to your coworkers or a stranger directly, and don't overdo it.

Collapse
 
grantdotdev profile image
Grant Riordan •

Take your comments on board with the hotfix, however it’s a lengthy comment , the one used merely as an example purposes was to highlight it can be done and has a brief explanation.

Commit message could have more detail.

Collapse
 
darkwiiplayer profile image
𒎏Wii 🏳️‍⚧️ •

I'm not generally a big fan of putting information that relates to the code in a commit message. In theory you could always git blame to find out why something was written, but in theory code can exist outside of its repository, so using a comment puts the explanation closest to where it's needed.

A commit message should generally focus on the what was changed more than the how does the code work, so there I'd care more about seeing 1. that it's a hotfix 2. what it does to fix it and 3. some context as to why this was necessary.

Coming up with a good concise example of a comment for a dev post while still showing off the subtleties of writing good comments is definitely hard, and my 3 lines are already about the shortest example I could come up with (out in the real world, these things often get a lot longer).

But I think your examples did just get a little too simple here and there and you lost some of the points you were making in the text (which I mostly agree with, by the way).

Thread Thread
 
grantdotdev profile image
Grant Riordan •

Thanks for the feedback.

Collapse
 
miketalbot profile image
Mike Talbot ⭐ •

Totally agree with this.

Collapse
 
axorax profile image
Axorax •

Agreed. I also like the Hotifx in the 3rd code block

Collapse
 
ingosteinke profile image
Ingo Steinke, web developer •

Another valid use case: TODO-comments

// TODO remove this workaround when framework bug #12345 got fixed
Enter fullscreen mode Exit fullscreen mode
Collapse
 
grantdotdev profile image
Grant Riordan •

definately- check out my blog on how to ensure these actually get done dev.to/grantdotdev/tech-debt-code-...

Collapse
 
andrewmat profile image
André Matulionis •

I agree with you that comments are stigmatized and we should be using more of this tool.

But where I disagree:

  • Complex code can use comments, but you should revaluate if this complexity is worth it, and if you could externalize its maintainancy. It may be better to add a sort package into your dependencies than create your own sort.

  • Overly verbose comments can be crucial. It should be used sparingly, but don't detract from your comment when trying to be succinct. It's better to have a paragraph than to not understand it.

  • A major argument I see against comments of that they are unmaintained by default. Comments should be updated, but nothing is making you update it. Just saying "don't let your comments be unmaintained" kinda skips this point placing the burden into the dev, and I miss this being addressed in your text.

I agree with most of your arguments, but had to say this

Collapse
 
wild-leo profile image
Leo •

I agree with you. However I think the way we want to convince ourselves, what is right and what is wrong, is somehow corrupted. Since you're trying to make sense out of it, and give this some reasonable explanation you've just entered battle you can't really win.

For example somebody pointed out this code:

user.discount = 0.2; // Premium members get a 20% discount
Enter fullscreen mode Exit fullscreen mode

is just simply redundant information... and it IS!
But I clearly see your point, and would advocate for this case.

We're trying to use some sense and logic in this debate... but comments are essentially way of communicating from one developer to another. And there are no mathematical rules in the way we speak. We usually rely on our guts.

And that's my point, we should just follow our intuition, still debate, but approach it more like a telling a story.

For me we should loosely follow those rules:
- use comments, but don't overuse them
- avoid stating obvious
- keep in mind comments need to be up to date
- comments are great for pointing out important context of code
- don't trust comments, there are only hints

And lastly it's not really that important. If you can give someone 15min advice how to improve commenting skills, go ahead. But lately I've met people who spend absurdly large amount of time correcting others how they should comment... and that's just counter-productive.

Collapse
 
tnypxl profile image
tnypxl •

Comments are great when you're working in legacy code. In situations where you have full control of the code from top to bottom, write code that is clear, not clever.

Collapse
 
martinbaun profile image
Martin Baun •

I like this take, and your piece is very well written!

Collapse
 
best_codes profile image
Best Codes •

This is a great article, I love it! Thanks for writing.

Collapse
 
axorax profile image
Axorax •

Code comments may not be evil but the developer writing the comments may be! 😶‍🌫️

Collapse
 
matthewbdaly profile image
Matthew Daly •

One case you don't mention is type hints. If you can document the type of something with native type hints, that's always a better option, and documenting it with comments as well is redundant unless there's additional information that can be expressed that way that can't be expressed with native type hints.

Collapse
 
grantdotdev profile image
Grant Riordan •

As type hints are tightly coupled with Python language, and this article is predominantly aimed at a more generic level, I feel it would be misplaced and irrelevant.

Collapse
 
matthewbdaly profile image
Matthew Daly • • Edited

Actually I wasn't referring to Python in this context. I work mostly in PHP and that's what I had in mind in my response.

Tools like Psalm let me express a lot more information about types than the native types can. For instance, I can specify that a string is the name of a class or interface, which can't be done with native type hints in PHP.

Collapse
 
rubdottocom profile image
rubdottocom •

🤡

// TODO: Add more comments
Enter fullscreen mode Exit fullscreen mode