Writing down a comment when you're coding might seem like you're going to help yourself or someone that might stumble upon your code, but, in reality, it might cause confusion and make your code less readable. If you're just starting out with coding, you sometimes feel that you need to comment every line to get your point across. That's probably not the case most of the time and you're probably just adding unnecessary noise to your code.
Code explanation
If possible, try to use the time you would spend on writing a comment on coming up with better naming or clearer code structures. Take a look at this
// check if employee can receive overtime pay
if (employee.isFullTime && employee.workHours > 160)
Instead of relying on the comment to explain the condition, it would be much wiser to create a function with a clear name that does this check
const isEmployeeEligibleForOvertimePay = (employee) => {
return employee.isFullTime && employee.workHours > 160;
}
if (isEmployeeEligibleForOvertimePay(employee))
It's now possible to reuse this small piece of code, as well as not have any doubts what this condition does. This might be a much larger condition, but a name might be sufficient enough to be aware what it's doing.
Of course, there is a case where it's very difficult to come up with a meaningful name or it's just not possible. In that case a comment would be helpful, but you should have that as a last resort.
Outdated comments
function insertData(data) {
store.user.insert(data); // updates the current user data
}
If you've been working on some older projects, something like this might've popped up. You can see that some data is being inserted, but the comment says otherwise. The comment might be right, although someone could have forgotten to delete it. This causes you to doubt the code and you're forced to check what's really going on in the insert method.
To prevent this, it's probably better to rename the functions to better represent their functionality and delete the unnecessary comment.
This is something that might happen with any comment. If someone forgets to update the comment after a couple of changes, another person can't be sure what's right or not. It's not a critical mistake and nothing will break because of this, but you might spend a couple of minutes/hours until you find out the truth.
Redundant comments
// checks whether the student lives in a dorm
if (student.livesInDorm)
I think we can all agree that these kinds of comments are totally unnecessary. You might feel better that you've written a couple lines of comments, but this doesn't help anyone when it's obvious what's happening
Separators
// ---------------
// VARIABLES
// ---------------
$blue: #1257ab;
This could be debated, but I think that the file structure should mandate where something belongs. By having these kinds of comments, you're just breaking up the flow of the code and not adding much value. If this is something that occurs a lot, having a defined standard with vertical formatting might have a much more appealing look.
Some people are more of a visual type, so separators can come in handy to visualize the various parts of a file, but I would still stay away from them.
Commented code
Nowadays, there's probably very little reason to keep commented out code in your codebase, especially if you're using a version control system. Anyone that will come upon the commented code won't be bothered to delete it because they haven't written in in the first place.
That will just perpetuate the old code into newer versions until it won't even work if you comment it out.
Do yourself a favour and delete the commented code. If you'll really need it, you can get it from your VCS' history.
Conclusion
Having comments in your codebase is something that requires constant attention. When you update a function, you must make sure you've updated its comment as well. That's why most of the comments you write go stale and just confuse you next time you bump into them.
By spending more time on naming your variables and functions, extracting a piece of code and adding vertical or horizontal formatting, you might even avoid the need for comments.
Even though I've shown the types of comments you should avoid, there are cases where it's a good idea to leave a comment (but not that many!).
- leaving a warning on a complicated feature that can't be managed with proper names is always a good idea
- documentation/legal comments in public code
Top comments (12)
Commenting on our own code is a part of planning, also it gives you a moment to rethink about your code and its necessity. Things become obsolete because they were written at a specific point of time in the past. Natural fact! Do not cry on that. Try to understand the difference between what is given and what you want. Then act accordingly. Avoiding things is not a solution to everything. Sit down, talk, think and act normal is the solution. Plus, this post seems to me a kickback of your frustration over something obsolete and wrong according to your present. It happens, but don't stop commenting. Everyone knows why the maker made comments. Follow the conventions while break the rules!
This article is more about writing inline comments inside of your code, not in a general sense of getting feedback on your code. I'm a 100% all for feedback on your code and getting better!
If I have misunderstood you, could you please clarify what you're saying?
I could have but I myself don't know what I say.
The only comment allowed is "TODO this code may not work for ...".
For the rest, write design and coding documentation and derive your code from that. Literate programming is one way, notebooks (these python things) is another.
I love this phrase from Uncle Bob:
That one caught my eye, too, it's pretty much what I tried to say :D
A variation on your complicated feature would be specification requirements since those tend to be longer-lasting and something the code is working towards.
Would you say that's a good thing to have in your code or not?
This post focuses more on writing inline comments within your code than on receiving feedback on your work in general. I wholeheartedly support obtaining feedback on your code and improving!
quordle
Another benefit of breaking up logic in small functions is to make it easier to write tests.
Agreed, definitely!
The take-home is : comments are good but over using it is bad... just like other coding principles like DRY. Thanks for the post....