The Right Way to Comment Your Code in JavaScript

One of the first things programmers learn is that they should add comments to their code. Each language has its own comment syntax.

In JavaScript, a single-line comment starts with // and runs until the end of the line, while multi-line comments are enclosed between /* and */.

New programmers tend to write lots of comments — often, too many. Worse, they tend to write bad comments. The combination of too many and bad comments can make software harder to maintain, because you have to

(a) find the code hidden between the comments,

(b) read through unnecessary comments, and

(c) often ignore them because they don’t add value.

What’s worse is when the code changes but the comments aren’t updated, creating confusion between what the comments say and what the code actually does.

Let’s start by describing what makes a good comment. As the old saying goes, comment why, not what. Here’s an example of a bad comment:

// Set the random seed
Math.random();

The comment is unnecessary. If you can’t understand that Math.random() is generating a random number, then the comment won't help much either. In this case, the comment is explaining what the code does, but the code itself is clear enough.

Here’s another example:

// Find the first user whose name matches the search string
for (let user of users) {
  if (user.firstName === searchString) {
    console.log("Found it!");
    break;
  }
}

If you don’t know how a for loop works, you probably shouldn’t be messing with this code yet. If you do know how it works, the comment doesn't add much value since the code itself is self-explanatory.

In both cases, the comments tell us what the code does, even though it's pretty obvious. I've seen tons of these kinds of comments, and I’m guilty of writing them myself.

So, what makes a good comment?

Your comments should explain why something is being done, not what is happening. Here’s a better version of the previous example:

// Searching in memory is faster than querying the database again
for (let user of users) {
  if (user.firstName === searchString) {
    console.log("Found it!");
    break;
  }
}

Here, the comment doesn’t explain what the code does. Instead, it explains why the code is written this way. It assumes you know how the code works and focuses on the reason behind this particular approach.

Comments like this often reflect business decisions or coding choices that might not be obvious to someone reading the code for the first time.

Once you start thinking in terms of why rather than what, you’ll notice that many comments suddenly seem unnecessary. In many cases, you can eliminate comments by using clearer variable and function names, making the code more self-explanatory. I’ll cover this in a future article, but choosing good names for your functions and variables can significantly improve the readability of your code—and reduce the need for comments.

Some people advocate for removing most comments. That’s an extreme stance, but I get where they’re coming from. So many comments are useless that it might seem better to leave them out entirely.

While I don’t think we should get rid of all comments, I do believe that comments should be a last resort, used only when better naming and structure don’t fully convey the intent.

Lastly, consider your audience: The person who will read your comments is likely a developer, probably under pressure, trying to debug your code.

Try to anticipate what they might be confused about or what might not be obvious to them. Help guide them to the tricky parts of the code.

Remember that the primary reader of your comments is often the future developer who has to maintain your program—and that developer might just be you.

I’m sure I’m not the only one who has read through code and comments, wondering which colleague wrote such a mess, only to realize that the culprit was me.