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...
For further actions, you may consider blocking this person and/or reporting abuse
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:
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:
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:
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.
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.
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).
Thanks for the feedback.
Totally agree with this.
Agreed. I also like the
Hotifx
in the 3rd code blockAnother valid use case: TODO-comments
definately- check out my blog on how to ensure these actually get done dev.to/grantdotdev/tech-debt-code-...
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
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:
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.
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.
I like this take, and your piece is very well written!
This is a great article, I love it! Thanks for writing.
Code comments may not be evil but the developer writing the comments may be! 😶🌫️
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.
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.
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.
🤡