Comments in JavaScript are lines of text that the engine completely ignores during execution. They exist for humans — to explain intent, document APIs, disable code temporarily, and leave notes for future maintainers.

Single-Line Comments

Single-line comments start with //. Everything from // to the end of the line is ignored.

  // This is a single-line comment
let x = 10; // Inline comment explaining the value

// You can comment out code during debugging:
// console.log(x);

Single-line comments are the most common style in modern JavaScript. Use them for brief explanations above a line or block of logic.

Multi-Line Comments

Multi-line comments begin with /* and end with */. They can span multiple lines.

  /*
 * This is a multi-line comment.
 * Useful for longer explanations or
 * temporarily disabling large blocks of code.
 */
let y = 20;

Multi-line comments cannot be nested — the first */ closes the comment:

  /* outer /* inner */ still broken */

JSDoc Comments

JSDoc uses multi-line comments starting with /** to document functions, classes, and modules. IDEs read JSDoc for autocomplete and type hints.

  /**
 * Calculate the factorial of a non-negative integer.
 * @param {number} n - The number to compute factorial for
 * @returns {number} The factorial of n
 * @throws {RangeError} If n is negative
 * @example
 * factorial(5); // 120
 */
function factorial(n) {
    if (n < 0) throw new RangeError('n must be >= 0');
    if (n === 0) return 1;
    return n * factorial(n - 1);
}

Common JSDoc tags:

Tag Purpose
@param Describe a function parameter
@returns Describe the return value
@throws Document exceptions
@example Show usage examples
@deprecated Mark API as obsolete

Comments in HTML Script Tags

Inside <script> tags, HTML comments do not work — only JavaScript comment syntax applies:

  <script>
    // Correct: JavaScript comment
    /* Also correct */

    <!-- This is NOT a JS comment — it may cause syntax errors in strict parsers -->
</script>

Best Practices

1. Explain Why, Not What

Bad — restates the code:

  // Increment i by 1
i++;

Good — explains reasoning:

  // Retry limit reached; fall back to cached response
return cachedResponse;

2. Keep Comments Up to Date

Outdated comments are worse than no comments. When you change logic, update or remove the comment.

3. Use TODO and FIXME Sparingly 

  // TODO: Replace hard-coded tax rate with API lookup (ticket #4521)
const TAX_RATE = 0.08;

// FIXME: Race condition when two tabs save simultaneously
function saveDraft(data) { /* ... */ }

Track TODOs in your issue tracker — don’t let them accumulate indefinitely.

4. Prefer Self-Documenting Code

Before adding a comment, ask whether a better variable or function name would eliminate the need:

  // Bad
const d = 86400000; // milliseconds in a day

// Good
const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;

5. Don’t Comment Out Dead Code — Delete It

Version control (Git) preserves history. Commented-out code clutters files and confuses readers.

  // Don't do this — use Git instead
// function oldImplementation() { ... }

Commenting Out Code for Debugging

Temporarily disable code during investigation:

  function processOrder(order) {
    validateOrder(order);
    // chargePayment(order);   // disabled while testing validation
    sendConfirmation(order);
}

Remove debug comments before merging to main.

Common Mistakes

Mistake Problem Fix
Nesting /* */ comments Syntax error Use // for inner comments
Commenting inside strings "// not a comment" — string content is literal No fix needed; be aware
Over-commenting obvious code Noise reduces readability Delete redundant comments
Using comments instead of tests Comments don’t verify behavior Write unit tests for complex logic

Troubleshooting

  • Syntax error near comment — Check for an unclosed /* block. Most editors highlight unmatched comment delimiters.
  • JSDoc not showing in IDE — Ensure the comment is directly above the function with no blank lines between.
  • Minifier removes comments — Production builds strip comments by design. Use JSDoc generation tools if you need published API docs.

Comments are a communication tool. Write them for the next developer (who might be you in six months), explain non-obvious decisions, and keep them accurate as the code evolves.