How To Write Comments in JavaScript

Why do we need comments?

Developers often write code that can be quite complex. This makes it difficult to read and understand programs. While it may make perfect sense to the person who wrote it, it may not be so obvious to someone new to the team who is looking at the code for the first time.

That's why comments are incredibly useful when it comes to understanding someone else's code.

And let me tell you, comments are not just for other developers; they're also helpful for your future self. Even after a few months, when you revisit your own code, you might not remember why you wrote a particular piece of code in the first place.

Comments in JavaScript are not executed by the JavaScript engine (the part of the browser that runs JavaScript code). They are simply ignored.

In JavaScript, there are two ways to write comments: single-line comments and multi-line comments.

Single-Line Comment

In a single-line comment, anything that comes after the two forward slash characters // on a line is ignored by the JavaScript interpreter. It means that the code or text after those slashes won't be executed or affect the program's behavior.

Single-line comments are usually used to provide brief descriptions of what a specific piece of code does.

let sum = 5 + 3; // The sum variable now holds the value 8

Multi-Line Comment

Sometimes, a single line of comment is not sufficient to fully document or explain why certain code is written in a specific way or what it actually does. In such cases, you can use multi-line comments.

To write a multi-line comment, you use the characters \* to start the comment and */ to end it. Anything between these characters is completely ignored by the JavaScript interpreter. It means that the code or text within the multi-line comment will not be executed or affect the program's behavior.

/*
The following code calculates the sum of x and y,
and assigns the result to the variable "sum".
It then prints the value of sum to the console.
*/

let sum = x + y;
console.log(sum);

Using Comments for Debugging

JavaScript comments can also be helpful for debugging purposes. They allow you to prevent certain parts of your code from executing while you're testing or troubleshooting.

When you want to test new features or locate bugs, you can use comments to temporarily prevent specific code from running. By progressively removing the comments, you can identify the problematic code that may be causing issues.

###1. Commenting Out Function Calls

When you're debugging, it's important to ensure that a function doesn't have any unexpected negative impacts on other parts of your code. One common testing strategy is to comment out the function and check if the rest of the program still runs correctly without it.

The below example comments out a call to the method doSomething to make sure it hasn’t affected the rest of the program before testing the method itself.

function doSomething(x) {
  let val = x / 2;
  return val;
}

let x = 1;
let y = 4;
// x = doSomething(y);  // call is commented out, "x" doesn't change

###2. Commenting Out Function Bodies

You don't always have to comment out an entire function when testing. Instead, you can comment out the body of the function using a multiline comment in JavaScript. By doing so, the function will still be called, but the value of x won't change because none of the code inside the function will be executed.

let x = 1;

function doSomething(z) {
  /*
	let a = z * z;
	x = a / 2;
*/
}

doSomething(12);

Best Practices For Comments

• Commenting should not be used as an excuse to write messy code and then try to fix it with lengthy comments. It's important to prioritize writing clean and clear code that is easy to understand, and comments should enhance it in a constructive way.

• While there are no strict rules for using comments, it's crucial for individuals or teams to agree on some best practices to ensure consistency. The key to effective JavaScript comments is maintaining a consistent style and ensuring that comments provide developers with a clear understanding of how the code works.

• Code should explain how it works, while comments should provide insights into why certain decisions were made. Avoid explaining how the code works in comments, as the code itself should be self-explanatory. If you find yourself explaining how, it might be a sign that your code needs refactoring.

// Do
let p = 3.14; // Rounded value of Pi
let c = 2 * p * 10; // Calculate the circumference of a circle with radius 10

// Don't
let p = 3.14; // Initiate the value of the variable p
let c = 2 * p * 10; // Multiply the value p into 20

• It's also important to avoid writing obvious and redundant comments. Only include necessary details and avoid going beyond what is required. Over-commenting can make code harder to read and maintain.

• Lastly, strike a balance by providing enough detail in comments without overwhelming the code's readability. Remember that maintaining and modifying comments can be challenging, so keep them concise and focused.