Comments in JavaScript

Analogy categoryAnalogies

1. Introduction

Comments are lines of text in source code that the JavaScript engine ignores during execution. They are used to explain why code exists, document function behavior, temporarily disable code during debugging, and leave notes such as TODOs for future work.

🏏

Cricket analogy: A coach's handwritten notes in the margin of the scoring book explaining why a bowling change was made aren't part of the official score, but they help future analysts understand the reasoning, just as JavaScript comments are ignored at runtime yet explain the code's intent.

2. Syntax

javascript

// This is a single-line comment

/*
  This is a
  multi-line comment
*/

/**
 * JSDoc-style comment used to document functions.
 * @param {number} price - the item price
 * @returns {number} the total with tax
 */
function total(price) { return price; }

3. Explanation

Single-line comments start with // and extend to the end of the line. Multi-line comments start with /* and end with */, and can span multiple lines or be placed inline within an expression. A special multi-line comment style starting with /** (JSDoc) is used by editors and documentation tools to describe function parameters, return types, and behavior, enabling autocompletion and type hints even in plain JavaScript.

🏏

Cricket analogy: A quick chalk mark '// check DRS' scribbled on the umpire's card is a one-line reminder, while a full paragraph taped inside the pavilion explaining the entire review protocol is like a multi-line block, and an official laminated rulebook page formatted for the broadcast graphics team to auto-generate on-screen stats is like JSDoc.

Gotcha: multi-line comments cannot be nested — writing /* outer /* inner */ still ends */ closes at the first */ it finds, leaving 'still ends */' as invalid code outside the comment, which causes a SyntaxError. Also, comments are stripped before execution, so they can never affect runtime behavior or performance, but overusing obvious comments (e.g. '// increment i' above i++) adds noise instead of value.

4. Example

javascript

// This is a single-line comment
let price = 100; // inline comment explaining the variable

/*
  This is a
  multi-line comment
*/
function calculateTotal(price, tax) {
  // TODO: validate inputs before calculating
  return price + price * tax;
}

console.log(calculateTotal(price, 0.08));

5. Output

text

6. Key Takeaways

// creates a single-line comment that runs to the end of the line.
/* ... */ creates a multi-line comment and can also be used inline within a line of code.
Multi-line comments cannot be nested — the first */ closes the comment.
/** ... */ (JSDoc) comments document functions and enable editor tooltips/autocompletion.
Comments are removed before execution and never affect runtime behavior, so use them to explain 'why', not to restate obvious code.