Clean Comments

Comments are sometimes used to explain thoughts that can’t be explained with code. Other times, they’re used to explain what some messy code is doing.

Do We Need Comments?

Most code should be self-explanatory. If it’s not, maybe we should think of a way to make it so. There are probably ways to make code clear enough so that comments aren’t needed.

Comments get outdated quickly as code changes since they’re often neglected when code changes. They aren’t updated as frequently as the code. This means that the code will deviate from the original code that it describes.

Code also moves around a lot. The comments don’t follow it.

We can update the comments as frequently as the code, but it’s probably better to make the code clear enough so that we don’t need the comments. The code is what we need to deal with in the first place. The comments are just there to support the code.

Inaccurate comments mislead the people who read the code. That’s not good since it leads to a wrong understanding of the code and bad changes can be made from it.

Comments Can’t Make Up for Bad Code

Comments may make some people more comfortable with writing bad code since they think they can make up for the mess with comments.

Clear code is much better than having messy code and lots of comments. The time writing comments is better spent on cleaning up the mess.

Let the Code Explain Itself

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

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

We can write:

The second example is better because it explains what the conditions actually mean. If we just look at the first condition, other people reading the code may not know what the conditions mean.

In the second example, we have the isEligibleForChildCareBenefits function and we know that it checks if an employee is eligible for child care benefits.

Good Comments

Some comments are necessary or beneficial. For example, sometimes we need a legal statement in the comments of our code.

Legal comments

Legal comments are sometimes needed because of corporate coding standards. This may include copyright information, licensing, and other information.

They shouldn’t form a contract or have a legal tone. We should refer to standard licenses or external documents whenever possible.

An example of this is:

// Copyright (C) 2020 by Foo Inc. All rights reserved

Informative comments

Sometimes we want to convey more information in the comments in addition to the code. But in most cases, they can be removed after naming things better.

An example of informative comments would be something like the following:

// Person instance being tested
let person = new Person();

In this case, we can just change the name to be more meaningful like:

let personBeingTested = new Person();

Explaining intent

Sometimes, we want to explain why we’re doing something in our code.

Clarification

We can also write comments to clarify something that we can’t change or we imported from other libraries that aren’t very clear.

For example, if we want to use Lodash’s chunk method to divide an array into an array of specified chunks, we may have to explain what we’re doing:

import * as _ from "lodash";// divide array into groups of 2
const arr = [1, 2, 3, 4, 5];
const splitArray = _.chunk(arr, 2);

This lets people know what the chunk the method does without looking at Lodash’s manual.

Warning of consequences

We may also use comments to let people know that running some code results in consequences.

For example, we can warn people about running slow code as follows:

const slowCode = () => {
  // slow code
}

To-do comments

It’s also common to leave comments in code that isn’t implemented yet. The code that’s not finished should be done eventually, but it can’t be done at the moment.

The comments may serve as a reminder to add or delete some code, or to clean them up in some way.

Emphasis

Comments can also be used to emphasize the importance of some code. It shows that the code is important so that people won’t overlook it.

JSDoc comments

When we’re writing libraries, we have to document or code to the masses that use them. We can do this with JSDoc by writing comments in our code, which will generate documentation from it.

They often look something like this:

These comments are needed because this is the way that people using our library will get information about how to use it.

Conclusion

Comments may be useful in some cases. We can use it to explain our decisions, put emphasis on certain pieces of code, warn people of consequences, and provide documentation for outside users.

Other than that, we can name things better and write better code to make it more self-explanatory instead of writing comments.