JavaScript Comments: A Complete Tutorial with Examples

Comments in JavaScript are used to explain code, make notes, or temporarily disable parts of code.

Comments are ignored by the JavaScript engine when executing the script.

Proper use of comments can help make your code easier to understand, both for yourself and for others who might read it in the future.

JavaScript supports two types of comments:

Single-line comments using //.
Multi-line comments using /* */.

1. Single-line Comments

Single-line comments in JavaScript start with //. Everything after the // on that line is treated as a comment and is ignored by the JavaScript engine.

Example 1: Using Single-line Comments

// This is a single-line comment
let x = 5; // This sets x to 5

console.log(x); // Output: 5

Explanation

// This is a single-line comment: This comment explains that the line is a comment.
let x = 5; // This sets x to 5: This inline comment provides information about what the code does.
Single-line comments can be used on their own line or at the end of a code line.

2. Multi-line Comments

Multi-line comments start with /* and end with */. They can span multiple lines, making them useful for longer explanations or temporarily disabling large blocks of code.

Example 2: Using Multi-line Comments

/* 
   This is a multi-line comment.
   It can span multiple lines.
   Useful for explaining complex logic or temporarily disabling code blocks.
*/
let y = 10;

/* Multi-line comments can also be used inline */
let z = 20; /* This is an inline multi-line comment */

console.log(y + z); // Output: 30

Explanation

/* … */ can be used to create comments that span across several lines.
Multi-line comments can be placed inline, but they are often used for block comments or detailed explanations.

Example 3: Disabling Code Blocks Using Multi-line Comments

/*
let a = 5;
let b = 10;
console.log(a + b);
*/
console.log('This code block is disabled.'); // Output: This code block is disabled.

Explanation

The code within /* … */ is “commented out” and will not execute.
This is useful for temporarily disabling code for debugging or testing purposes.

3. Commenting Best Practices

Explain Complex Code: Use comments to explain complex code logic, especially if it involves multiple steps or algorithms.
Avoid Over-commenting: Don't comment on obvious code. For example, don't write // Increment x by 1 next to x++; unless it's part of a complex logic.
Update Comments: Ensure that comments are kept up to date with changes in the code to avoid misleading information.
Use Comments to Debug: Temporarily disable parts of your code using comments to isolate problems during debugging.

Example 4: Explaining Complex Code

// Function to calculate the factorial of a number
function factorial(n) {
  // If n is 0, return 1 (base case for recursion)
  if (n === 0) {
    return 1;
  }

  // Otherwise, multiply n by the factorial of n-1 (recursive call)
  return n * factorial(n - 1);
}

console.log(factorial(5)); // Output: 120

Explanation

Comments are used here to explain what the factorial function does and describe each part of the function in a clear way.

4. Commenting Code for Debugging

Use comments to temporarily disable sections of code for testing and debugging.

Example 5: Using Comments for Debugging

let total = 0;
for (let i = 1; i <= 5; i++) {
  total += i;
  // console.log('Current total:', total); // Uncomment this line to debug the loop
}

console.log('Final total:', total); // Output: Final total: 15

Explanation

The console.log() inside the loop is commented out. It can be uncommented during debugging to trace the loop's execution.

5. Nested Comments: Beware!

JavaScript does not support nested comments, so avoid attempting to nest /* … */ comments inside other /* … */ comments.

Example 6: Incorrect Nested Comments

/*
let x = 10;
/* Nested comment - This will cause an error */
let y = 20;
console.log(x + y);
*/

Explanation

The code above will cause a syntax error because /* … */ comments do not support nesting.
To avoid issues, use single-line comments (//) if you need to comment within a multi-line comment.

6. Using Comments in Real-world Scenarios

Example 7: Providing Documentation for Functions

/**
 * Calculates the sum of two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @returns {number} The sum of a and b.
 */
function add(a, b) {
  return a + b;
}

console.log(add(3, 7)); // Output: 10

Explanation

The comment block is formatted as a JSDoc comment, commonly used for documenting functions, parameters, and return values in JavaScript.
This format can be parsed by documentation generation tools.

Summary

JavaScript comments are a valuable tool for explaining code, improving readability, and assisting in debugging. Here's a quick recap of the types and usage:

Best Practices

• Explain Complex Code: Use comments to explain parts of the code that might be difficult to understand.
• Avoid Redundant Comments: Don't comment on self-explanatory code.
• Update Comments: Keep comments relevant as code evolves.
• Use for Debugging: Comment out sections of code for testing or debugging.

Proper commenting practices make your code easier to maintain and understand, both for you and others working on your project.