JavaScript Comments

By the end of this lesson, you will be able to add single-line and multi-line comments in JavaScript to explain code without changing how it runs.

What it is

A comment is text that JavaScript ignores when it runs your program. Comments are for people reading the code, not for the computer. JavaScript supports two main comment styles: // for a single line and /* ... */ for a block that can span multiple lines. A related term is documentation comment, often written as /** ... */ and used with tools such as JSDoc to describe functions, parameters, and return values.

Think of comments as notes in the margin of a textbook. The code is the sentence; the comment explains why the sentence exists, what assumption it makes, or what edge case it handles.

Why it matters

• Comments explain intent, such as why a formula uses 0.08 instead of 8.
• They help teammates understand unfamiliar code quickly.
• They mark temporary notes like TODO or FIXME without affecting execution.
• Documentation comments can generate API docs and improve editor tooltips.
• They can isolate a problem by temporarily disabling a line during debugging.

Syntax or steps

1. For one line, start with //. Everything after it on that line is ignored.
2. For multiple lines, start with /* and end with */.
3. For function documentation, start with /** and include tags such as @param and @returns.
4. Keep comments short, current, and focused on non-obvious information.

Example

/**
 * Calculate the total price after tax.
 * @param {number} subtotal - Price before tax.
 * @param {number} taxRate - Decimal tax rate, e.g. 0.08.
 * @returns {number} Total price rounded to two decimals.
 */
function calculateTotal(subtotal, taxRate) {
  // Apply tax, then round to cents.
  const total = subtotal * (1 + taxRate);
  return Math.round(total * 100) / 100;
}

/*
  Example usage:
  calculateTotal(50, 0.08) -> 54
*/
console.log(calculateTotal(50, 0.08));

The first block is a documentation comment. It describes the function and its inputs. The // comment explains the rounding step. The final /* ... */ block is a multi-line note showing expected usage. The program still runs normally because comments are not executed.

Common mistakes

• Forgetting to close a block comment. If you write /* but no */, the rest of the file may be treated as comment text. Fix it by adding the closing marker.
• Trying to nest block comments. JavaScript block comments do not nest, so /* outer /* inner */ still outer */ ends at the first */. Use separate comments or avoid nesting.
• Commenting obvious code. // set x to 1 above let x = 1; adds noise. Replace it with a clearer variable name or explain a non-obvious reason.
• Leaving stale comments. If code changes but the comment does not, the comment becomes misleading. Update or delete it whenever behavior changes.

When to use it

Use comments when the code cannot explain itself clearly. Prefer meaningful names for simple facts, and use comments for reasons, constraints, and complex logic.

Practice

Guided exercise: Write a function called getDiscountedPrice that takes price and discountPercent. Add a documentation comment, a single-line comment explaining the calculation, and a multi-line comment showing an example call.

Challenge: Temporarily disable the console.log line using a single-line comment, then re-enable it using a block comment around the original line. Expected output after re-enabling: 45 if the price is 50 and the discount is 10.

Quick check

Which comment style should you use to document a function’s parameters and return value?

Answer: Use a documentation comment such as /** ... */ with tags like @param and @returns.

Summary

JavaScript comments are ignored by the engine and exist to help humans understand code. Use // for short notes, /* ... */ for multi-line notes, and /** ... */ for structured documentation. The best comments explain why, not merely what.