Maintainable JavaScript — Multiline Comments

Creating maintainable JavaScript code is important if want to keep using the code.

In this article, we’ll look at the basics of creating maintainable JavaScript code by creating better multiline comments.

Multiline Comments

Multiline comments are comments that can span multiple lines.

They start with /* and ends with */ .

Multiline comments don’t have to span multiple lines.

For instance, we can write:

/* one line comment */

We can also write:

/* two line
comment */

or:

/*
two line
comment
*/

They’re all valid, but it’s better to put the asterisk on the left side so we won’t confuse it for code.

For example, we can write:

/*
 * two line
 * comment
 */

This is neater and delimits all the comment content.

Multiline comments always come before the code they describe.

They should be preceded by an empty line and should be at the same indentation as the code we’re commenting on.

For instance, we should write:

if (hasAllPermissions) {

  /*
   * if you made it here,
   * then all permissions are available
   */
  allowed();
}

We added a line before the comment to make it more readable.

This is better than:

if (hasAllPermissions) {
  /*
   * if you made it here,
   * then all permissions are available
   */
  allowed();
}

which has no line before it.

We should also have a space between the asterisk and the text.

For instance, we can write:

if (hasAllPermissions) {

  /*
   *if you made it here,
   *then all permissions are available
   */
  allowed();
}

It’s hard to read after the asterisk without a space.

We should also have proper indentation, so we shouldn’t write:

if (hasAllPermissions) {

/*
 *if you made it here,
 *then all permissions are available
 */
  allowed();
}

The intention should match the code that the comment is commenting on.

Also, we shouldn’t use multiline comment for trailing comments.

For instance, we shouldn’t write:

let result = something + somethingElse; /* they're always numbers */

We should leave multiline comments for block comments.

Using Comments

What to comment on is always a controversial topic.

But there’re some common conventions that most people accept.

One thing we shouldn’t do is to comment on things that are already described by the code.

So we shouldn’t have comments like:

// set count
let count = 100;

We know that we’re setting count by looking at the code, so we don’t need a comment for that.

But if there’s something that needs explaining, then we can do that.

For instance, we can write:

// this will make it rain
let count = 100;

Now we know changing count will make it rain.

Difficult-to-Understand Code

If we have hard to understand code, then we should put a comment on it.

If there’s anything that’s hard to understand by just reading the code, then we should add some comments.

Conclusion

We should be careful when using multiline comments.

Also, if we have anything that’s not obvious from the code, then we should write a comment on it.