JavaScript Comments

Comments are text in your code that JavaScript completely ignores. They exist only for humans. They have two jobs: explaining code so it is easier to read (including by you, three weeks from now), and switching code off temporarily while you test something.

// Single-Line Comments

A single-line comment starts with //. Everything from the // to the end of that line is ignored.

You can put a comment on its own line, above the code it describes:

// Set up the prices
let price = 100;
let tax   = 0.08;

// Work out the total including tax
let total = price + (price * tax);

Or at the end of a line of code, to explain just that line. This is called an end-of-line or inline comment. The code before the // runs; the rest of the line is skipped:

let x = 5;      // Declare x, give it the value of 5
let y = x + 2;  // Declare y, give it the value of x + 2
console.log(y);

// Multi-Line Comments

For longer explanations, start with /* and end with */. Everything between them is ignored, however many lines it covers. This is also called a block comment:

/*
  Converts a temperature from Celsius to Fahrenheit.
  Formula: (C × 9/5) + 32
  The result is rounded to one decimal place.
*/
function toFahrenheit(celsius) {
  let f = celsius * 9 / 5 + 32;
  return Math.round(f * 10) / 10;    // round to 1 decimal
}

console.log(toFahrenheit(100));
console.log(toFahrenheit(37));

A block comment can also sit in the middle of a line, which a // comment cannot: let area = width /* in meters */ * height;. That is rare, but you will see it.

Single-line comments are by far the most common. Block comments tend to be used for longer, more formal documentation, such as describing what a function does at the top of it. Many projects use a special form that starts with /**. Editors like VS Code read it and show your description as a tooltip wherever the function is used:

/**
 * Adds tax to a price.
 * @param price  the price before tax
 * @param rate   the tax rate, e.g. 0.08 for 8%
 */
function withTax(price, rate) {
  return price + price * rate;
}

To JavaScript, /** ... */ is just an ordinary block comment. The extra star and the @param lines are a convention called JSDoc, read by tools, not by JavaScript itself.

/* outer comment
   /* inner comment */
   this line is no longer inside a comment
*/

// Using Comments to Prevent Execution

Putting // in front of a line of code turns it from something that runs into a comment. This is called commenting out code, and it is one of the most useful testing tricks there is: you can switch a line off without deleting it, and switch it back on by removing the //.

let score = 85;
// score = score + 10;      switched off for now
console.log(score);

Remove the // and run it again: the output becomes 95.

To switch off several lines at once, wrap them in a block comment:

let lives = 3;
/*
lives = lives - 1;
lives = lives - 1;
*/
console.log(lives);

This is a real debugging technique. When something is broken and you do not know which line is the cause, comment out half the suspect code. If the problem goes away, it was in the half you switched off. Keep halving until you find the line.

// Writing Good Comments

Good code mostly explains itself through clear names. Save comments for the things the code cannot say on its own, usually why something is done:

// Bad comment: just repeats what the code already says
let age = 18;     // set age to 18

// Good comment: explains WHY
let minAge = 18;  // legal voting age in this state

• Explain why, not what. Anyone can read what minAge = 18 does. The comment is useful because it says where 18 comes from.
• Keep comments up to date. A comment that no longer matches the code is worse than no comment, because readers will believe it.
• Delete dead code eventually. Commenting out is for testing. Once you are sure a line is not needed, remove it rather than leaving it switched off forever.

// Quick Check

let total = 10;
total = total * 2;   // total = total + 100;
console.log(total);

let msg = "Visit //citicoding.org";
console.log(msg);

let n = 1;
/* n = 5;
n = 10; */
n = n + 1;
console.log(n);

// Try It

▶ Open Playground

1. Click Open Playground and run it. Line 2 starts with //. Which value of x is logged, and why?
2. Remove the // from line 2 and run it again. What changed?
3. Write three lines that change a variable, wrap the middle one in /* */, and predict the result before you run it
4. Select several lines and press Ctrl+/ (Cmd+/ on a Mac) to comment them all out. Press it again to switch them back on. The same shortcut works in VS Code