Try to avoid comments (most of the time)
Tags: engineeringmonday, javascript
Published: 2021-05-31 13:36:50

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
```js
// 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
```js
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
```js
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
```js
// 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
```scss
// ---------------
// 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