You left out what you SHOULD comment. The rule is simple. Don't explain what the code does, explain what the intentions of the code are. Anyone can tell what the code is doing by looking at it, but it can often be impossible to understand why it's being done just by looking at the code alone.
I might add a new article about which comments to write but this was off the topic I wanted to discuss here,
However, the idea that comments should be adding value or describing an original logic, not translate syntax is mainly what most good comments are about, right?
My name is Tobias, I'm 30 years old and living in Augsburg, Germany. I am working as a software developer for over 7 years now. Nowadays I'm working with react, react-native, node.js, graphql, ...
I agree with the "comment why, not how" a lot. I'm actually a big fan of comments and push for developers to leave more, but I focus on the spots where the code can't be simplified anymore and it's still hard to read. Or the reason behind why we are doing it isn't clear.
It's easy to forget the business or technical reason why we had to do something and then not be able to find the ticket a year later explaining it.
Especially with the cadence that language and frameworks are updated today. The more efficient techniques may not have been available when the code was written. I personally have left a whole bunch of notes at the top of a Vue project explaining why I didn't use separate component files and modules (inexperienced dev team, no source code control implementation on site, no experience of setting up build pipelines etc.)
Absolutely. For all the modern proclamations of "self-documenting" code, code can only show what it's doing, not why. Comments are still invaluable for explaining why something is happening, and sometimes, why it hasn't been done a different way (one which might have face validity, but be wrong).
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
You left out what you SHOULD comment. The rule is simple. Don't explain what the code does, explain what the intentions of the code are. Anyone can tell what the code is doing by looking at it, but it can often be impossible to understand why it's being done just by looking at the code alone.
I might add a new article about which comments to write but this was off the topic I wanted to discuss here,
However, the idea that comments should be adding value or describing an original logic, not translate syntax is mainly what most good comments are about, right?
Great article. This an often overlooked but important topic.
I look forward to the follow up - “Don’t get rid of all comments”
THIS! Comments for intentions and not repeating what the code is doing
That's a good advice, I've heard the same principle in the short form "Comment why, not how."
Yeah, I couldn't agree more 😅
I agree with the "comment why, not how" a lot. I'm actually a big fan of comments and push for developers to leave more, but I focus on the spots where the code can't be simplified anymore and it's still hard to read. Or the reason behind why we are doing it isn't clear.
It's easy to forget the business or technical reason why we had to do something and then not be able to find the ticket a year later explaining it.
Especially with the cadence that language and frameworks are updated today. The more efficient techniques may not have been available when the code was written. I personally have left a whole bunch of notes at the top of a Vue project explaining why I didn't use separate component files and modules (inexperienced dev team, no source code control implementation on site, no experience of setting up build pipelines etc.)
100% agree
Absolutely. For all the modern proclamations of "self-documenting" code, code can only show what it's doing, not why. Comments are still invaluable for explaining why something is happening, and sometimes, why it hasn't been done a different way (one which might have face validity, but be wrong).