JavaScript Clean Code — Bad Comments

Subscribe to my email list now at http://jauyeung.net/subscribe/

Follow me on Twitter at https://twitter.com/AuMayeung

Many more articles at https://medium.com/@hohanga

Even more articles at http://thewebdev.info/

Comments are sometimes using to explain our thoughts which can’t be explained with code. Other times, it’s used to explain what some messy code is doing.

In this article, we’ll look at various types of bad comments.

Most comments are bad comments. They’re used to explain bad decisions or bad code. We should avoid these kinds of comments.

Mumbling

Adding comments just because we feel like it or the process requires it isn’t a good reason to put in comments.

At least the comments have to be useful if we’re to write them. For example, if we have:

try {
  loadProperties();
} catch (e) {
  // No properties means everything is loaded
}

Then we have a comment that isn’t very useful in the catch block. We have no idea what the author is trying to say.

We don’t know what ‘properties’ mean. When is everything loaded? It just doesn’t tell us too much useful information.

It probably confuses more people that help them. We probably end up just looking at the code to see what the loadProperties function does to gain knowledge of the code.

Redundant Comments

These are comments that explain the same thing that is already explained by the code.

For example, if we have:

// adds 2 numbers;
const add = (a, b) => a + b;

Then the ‘adds 2 numbers’ comments are redundant because we already know that the function is called add and it takes 2 numbers and returns the sum of them. Therefore, we don’t need a comment before it to explain what’s already shown in the code.

Misleading Comments

Misleading comments lead developers that are working on a piece of code to have the wrong understanding of the code and make bad decisions and create bugs.

Thus obviously isn’t food. It leads to more time debugging to find out why something won’t work as they described in the comments.

Mandated Comments

If a piece of code isn’t for the public to use, then there’s no read to have comments for them since we don’t need to generate documentation for them.

It just clutters up the code file with extra text that doesn’t do much to help readers and other developers.

Journal Comments

Writing a long comment with the log of all the changes to a piece of code is useless. They’re long and don’t provide much information since we already have the change history in our version control systems.

If we aren’t using version control to version our code, it’s time to use it now so we can log the change history, create copies with branches and merge different people’s code together into one as a team of people works on it.

Noise Comments

Noise comments are nothing but noise. They’re useless and just take up space on the screen and on disk.

We go back to this example:

// adds 2 numbers;
const add = (a, b) => a + b;

This is obviously not very useful since the code already explains everything the same way as the comments.

Don’t Use Comments when Identifiers Can be Named Better

We can easily write code that explains themself. For example, instead of writing:

// check if employee is eligible for child care benefits
if (employee.salary < 50000 && employee.hasChild) {
  //...
}

we can write:

const isEligibleForChildCareBenefits = (employee) => {
  return employee.salary < 50000 && employee.hasChild;
}

if (isEligibleForChildCareBenefits(employee)) {
  //...
}

Our new function explains the same thing as the comments, but with fewer words.

Comments also get outdated fast since they’re often neglected when the code is being changed.

Photo by Ansley Ventura on Unsplash

Position Markers

Some developers like to put position markers like the following:

// //////////

The use of these extra comments is questionable most of the time. Only use them if they’re actually important.

Closing Brace Comments

Some people like to mark lines with closing braces with a comment as follows:

if (employee.salary < 50000 && employee.hasChild) {
  //...
} // if

This is stating the obvious and so it’s not that useful. Most text editors and IDEs highlight the opening and closing braces anyways when your cursor it over it so we won’t miss them.

Attributions and By-Lines

This is something like:

/* Added by Bob */

Source control systems provide this information already, so we definitely don’t need them in our code.

Commented-Out Code

Commented our code clutters up our files and screen. Also, it doesn’t provide any value since they’re commented out. It also leads developers to read the code to question why they’re commented out in the first place.

It’s easy to mislead developers with them, so they should be removed. If the program still works with them commented out, they don’t need to be in the code.

If we need them back, we can get them back from the source control system’s change history.

HTML Comments

HTML comments definitely don’t belong in code. Humans can’t read them. Therefore, it should be the documentation program’s responsibility to generate HTML code from our human-readable comments.

Too Much Information

Nobody wants to read an essay in the comments, so we shouldn’t write one. Better just to keep it short if we need them at all.

JSDoc in Nonpublic Code

Code that isn’t exposed to the public doesn’t need to be documented like they’re made for the public. So we shouldn’t do it and save ourselves lots of time documenting code that shouldn’t be documented.

Conclusion

As we can see, there’re many types of bad comments. We should avoid all of them to save our own and other developers’ time. They don’t contribute any value or they mislead people, which is even worse.

The post JavaScript Clean Code — Bad Comments appeared first on The Web Dev.