JavaScript — Comments

Two native syntaxes

// Line comment — everything after the slashes on this line is ignored

/* Block comment — can span
   as many lines as needed */

let active = true;   // trailing notes sit at line-end too

What they're for

The interpreter skips both forms completely — comments exist only for humans (and documentation tools).

Disabling code temporarily

The debugging reflex:

processPayment(cart);
// applyDiscount(cart);   ← disabled while testing
sendReceipt(cart);

Wrap whole blocks with /* */:

/*
function experimentalRender() {
    // risky new approach under evaluation
}
*/

Nesting warning: block comments don't nest. The first */ closes everything:

/* outer
   /* inner */
   this line is LIVE code again! */

Commenting out code that already contains /* */ breaks mysteriously. Prefer line comments (//) for disabling code — they stack safely.

JSDoc — comments that become documentation

A convention so widespread that editors parse it:

/**
 * Convert Celsius to Fahrenheit.
 * @param {number} celsius
 * @returns {number} temperature in °F
 */
function toFahrenheit(celsius) {
    return celsius * 9 / 5 + 32;
}

Type the function name elsewhere and your editor shows this description inline. Teams generate full API docs from these blocks. The tags worth memorizing: @param, @returns, @example.

What deserves a comment

✅ Explain WHY

// Retry 3x because the payment API drops ~1% of requests silently
for (let attempt = 0; attempt < 3; attempt++) { … }

// ms not seconds — matches the server timeout contract
const POLL_INTERVAL = 15000;

✅ Warn and reference

// TODO: replace with real auth once backend ships
// FIXME: races when two tabs open — see issue #142
// HACK: Safari needs this wrapper; remove when fixed

TODO/FIXME/HACK are searchable conventions every editor highlights.

❌ Narrate the obvious

// increment i by one
i++;

// set name to Ada
let name = "Ada";

Zero information, pure noise. If the code reads clearly, silence is correct.

Comments are public

Browsers download your JS exactly as written (unless bundled/minified). Anything in comments ships to users:

// NEVER: api key = sk_live_abc123
// NEVER: admin password reset flow bypasses email check

Secrets live in server-side environment variables — never client-side anything.

Team style in one paragraph

Real codebases agree on conventions: some ban block comments for code (line-only), require JSDoc on exported functions, or demand a ticket number on every TODO. Read the project's existing files before writing yours — matching local style beats imposing global taste.

Mini Practice

1. Disable three lines with //; then wrap them in /* */ and add an inner /* */ — watch it break
2. Write proper JSDoc for a two-parameter function; hover its call site in VS Code
3. Seed a file with one TODO and one FIXME including ticket numbers
4. Find one obvious-comment and delete it without guilt

Next: variables → (rewrite pending — next new topic: let)