Maintainable JavaScript — Comments and Statements

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 writing comments and statements properly.

Potential Author Errors

If there’re author errors in the code, then we should comment on them so that they can be fixed.

At least someone can check if it’s actually an error.

For example, if we have:

while (element && (element = element[axis])) {
  // NOTE: assignment
  if ((all || element[TAG_NAME]) &&
    (!fn || fn(element))) {
    return element;
  }
}

then some people may think that the assignment operation in the while loop head is a mistake.

This is a valid syntax, so we can use it.

It’s not a mistake, so we tell readers that it’s not with a comment.

It may be flagged by some linting tools since we usually don’t use assignments in our loop header.

Browser-Specific Hacks

If we need to make our code work with multiple browsers, then we may need to write hacks to make them work with some specific browser.

This is common when we need to make our front end code work with Internet Explorer.

If we have hacks in our code, we should make comments on what we’re doing so people know what’s going on.

This should be less common as browsers become more standardized.

Documentation Comments

Comments can be used for documentation with programs like JSDoc.

For example, we can write:

/**
  add 2 numbers together
  @method add
  @param {number} x - a number
  @param {number} y - another number
  @return {number} the sum of 2 numbers
**/
function add(x, y) {
  return x + y;
}

We have the add function that has 2 parameters.

We add some comments about the parameters so we know the type of the parameters.

Also, we do the same with the return type.

This can be read with a documentation generator to create our documentation.

We should document all methods, including the expected arguments and possible return values.

Constructors should have comments with the custom type and expected arguments.

Other objects that have one or more methods can have comments on the methods.

They must be documented for proper documentation generation.

The document generator would determine how the comments should be formatted.

Statements

Statements like if or for can be used in 2 ways in JavaScript.

We can have the curly braces or we can skip them if our block is only one line long.

However, skipping the curly braces is bad since it’s hard to tell where the block starts or ends.

So instead of writing:

if (condition)
  doWork();

or

if (condition) doWork();

or

if (condition) { doWork(); }

We should write:

if (condition) {
  doWork();
}

Having the body below the first line is better than having it on the same line.

The curly-brace surrounds the block and it’s easy to tell where the block starts or ends with them.

Conclusion

Comments should be added for potential errors or hard to understand code.

Also, statements should be surrounded with curly braces.