The Power of Code Comments

Inline

Inline comments should be very short and very specific, explaining the exact line where we write them.

const d = new Date(); // Get today's date

Single Line

Single line comments are generally used to describe what a line of code does or the next block of code if they share the same responsibility.

// Get today date in days
const date = new Date();
const day = date.getDate();

We just described what a block of code does using a single line comment, which is more than enough for this case.

Multi-line

Multi-line comments are used to describe the purpose of a big chunk of code.

There is two ways to create a multi-line or block comments.

/*
   This file is responsible for generating inspiring quotes.
   We can also detail any requirement or even relevant links in here.
*/

The above example is completely valid, however, most developers prefer the next approach.

/**
 * This file is responsible for generating inspiring quotes.
 * We can also detail any requirement or even relevant links in here.
 */

Annotations

Annotations is a special kind of comments. Well, not really, it’s more like a set of tags you can write in a block comment which by turn enables your code editor to offer accurate code completion, parameter info, type hinting and much more.

Not only that, some frameworks heavily rely on annotations to function or generate accurate documentation.

Although annotations are not limited to a single language, they can behave differently based on the language you’re using, but they’re still extremely powerful tool anyway.

/**
 * Combine first and last name into a full name.
 *
 * @param {String} firstName
 * @param {String}  lastName
 * @returns {string} fullName
 */
function getFullName(firstName, lastName) {
  return `${firstName} ${lastName}`;
}

Using annotations in the example above to describe what this function does, as well as defining the parameter and return types, makes it much easier for any developer using your code to provide accurate arguments and know what kind of return type to expect.

Keep it short

Comments should summarize what your code does so keep it short, descriptive and to the point. No one like to read a long essay.

Abusing comments

Yes comments are helpful tool but overusing them can be redundant in some cases, consider this code below:

const d = new Date(); // Assign today's date to variable d

Instead of a comment explaining what’s going on here we can utilize the code in this case to make a self-documenting code. We can change our code to:

const today = new Date();

There is no need for a comment in this case. Just by changing the variable name the code has become self-explanatory.

Avoid redundant comments

Sometimes the function name can be self-explanatory, the name tells you exactly what the function does. If your comment simply repeat the function name then it doesn’t provide any real value, consider the example below:

/**
 * Get full name.
 *
 * @param {String} firstName
 * @param {String}  lastName
 * @returns {string} fullName
 */
function getFullName(firstName, lastName) {
  return `${firstName} ${lastName}`;
}

We can argue that this comments doesn’t really provide any useful data beside the parameter type hinting. This should be avoided.

Let’s try to be more descriptive.

/**
 * Combine first and last name into a full name.
 *
 * @param {String} firstName
 * @param {String} lastName
 * @returns {string} fullName
 */
function getFullName(firstName, lastName) {
  return `${firstName} ${lastName}`;
}

Yea I know there is no much to be said here anyway, but you get the idea. At least our comment isn’t completely useless.

Use Tags

Annotation tags are an amazing and very powerful tool, they unassuming and redundant at first, but trust me, they can work wonders in making your code crystal clear.
Use @param and @return whenever you can, even if the parameters are super obvious.