DEV Community

loading...
Bornfight

Try to avoid comments (most of the time)

shockwavee profile image Davor Tvorić ・3 min read

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)
Enter fullscreen mode Exit fullscreen mode

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))
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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;
Enter fullscreen mode Exit fullscreen mode

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

Discussion (12)

Collapse
hugekontrast profile image
Ashish Khare😎

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!

Collapse
shockwavee profile image
Davor Tvorić Author

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?

Collapse
hugekontrast profile image
Ashish Khare😎

I could have but I myself don't know what I say.

Collapse
jhelberg profile image
Joost Helberg

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.

Collapse
nevcos profile image
Filipe Costa

I love this phrase from Uncle Bob:

A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail.

Collapse
shockwavee profile image
Davor Tvorić Author

That one caught my eye, too, it's pretty much what I tried to say :D

Collapse
thebarefootdev profile image
thebarefootdev

Great! I am in the same mind as this. Code over Comments.

Well written!

Collapse
oadrian2 profile image
oadrian2

A variation on your complicated feature would be specification requirements since those tend to be longer-lasting and something the code is working towards.

Collapse
shockwavee profile image
Davor Tvorić Author

Would you say that's a good thing to have in your code or not?

Collapse
baukereg profile image
Bauke Regnerus

Another benefit of breaking up logic in small functions is to make it easier to write tests.

Collapse
shockwavee profile image
Davor Tvorić Author

Agreed, definitely!

Collapse
drsimplegraffiti profile image
Abayomi Ogunnusi

The take-home is : comments are good but over using it is bad... just like other coding principles like DRY. Thanks for the post....

Forem Open with the Forem app