JavaScript Comments: Improving Code Readability

In this tutorial, you'll learn how to comment in JavaScript.  We'll discuss one of the most important and often overlooked features of many programming languages. Comments. In particular, JavaScript comments.

When writing code, it's important to notate complex logic that may confuse others looking at your code down the road. It may even confuse you if it's been long enough and you don't remember what a particular chunk of code was supposed to do, or why you even wrote it in the first place.

Enter JavaScript comments, the savior of all confusion prevention and code readability since 1995!

The Purpose of Comments in JavaScript

You've created an amazing application with tens of thousands of lines of code. There are tons of great features and functions that bring your app to life.

Suddenly, your application crashes and you need to debug it. But there's nothing in your code that outlines what each piece does or how it works! What now?!

Well, if you took the time to break your code out into separate, easily readable blocks with comments notating their purpose, then it would be a lot easier to find what you're looking for.

Think of comments as documentation for your code. If it's not well documented, it could make it difficult to find what you're looking for quickly. Or, if you're working on a project with a team of developers, it could also make it easier for them to piece together the code and determine why certain blocks of code exist.

Think of comments as documentation for your code. If it's not well documented, it could make it difficult to find what you're looking for quickly. Or, if you're working on a project with a team of developers, it could also make it easier for them to piece together the code and why certain blocks of code exist.

Creating Single-Line Comments

There are different types of comments you can create in JavaScript. The first type is a single-line comment. As you guessed, they're comments that exist on one line only and can be created using two slashes //:

// This is a single-line comment

Pretty simple, right? Comments don't have to stand alone on their own line. You can also append comments to the end of a line. This is highly beneficial for notating variable definitions:

var i = 0; // index set to 0

If your comments are too long for a single line, you can create multiple single-line comments like this:

// This is the first line
// This is the second line

As a general rule, I add comments before each function call I create:

// do something:
function func_1() {
	// ...
}

// do something else:
function func_2() {
	// ...
}

This helps organize each chunk of code for easier readability and also briefly explains what each function does so it's easier to find later on.

Creating Multi-Line Comments

The cleaner way to approach multi-line comments, also known as comment blocks, is to use the slash and asterisk characters:

/* First line
 * Second line
 * Third line */

You can also use multi-line comments in JavaScript for commenting out large chunks of code if you no longer need them:

var i = 1;
/*
var j = 2;
var k = 3;
*/

console.log(i);
console.log(j);
console.log(k);

// 1
// undefined
// undefined

This code snippet defines three variables, i, j, and k and attempts to output them to the console. This works for the first variable, but the others show undefined as the value because they're commented out in the code.

Commenting chunks of code out is a great way to retain code that you think you may use later on, or if you need to remove some functionality to test other pieces without some of the code interfering.

Multi-line comments in JavaScript are also very useful in cases where you need to describe certain functions in greater detail.

Conclusion

This tutorial taught you how to comment in JavaScript.

In my opinion, you can never have too many comments in your code. Code readability is important and, overall, should be clean enough to understand what's going on quickly without aimlessly glossing over it.

Comments help organize and briefly explain what the different sections do, so it's important to follow this practice in all of the applications you create.