Two Kinds of Comments
JavaScript has two comment syntaxes. A single-line comment starts with // and runs to the end of the line:
A block comment starts with /* and ends at the next */. It can span as many lines as you want:
Both forms are completely ignored by the JavaScript engine. They exist for humans — for you, for your teammates, and for future you reading this code in six months.
Single-Line Comments
// is the one you'll use most. Anything on the same line after // is a comment; the next line goes back to being code:
Trailing comments (after a statement) are fine for short notes. If the note gets long enough that it wraps, move it to its own line above the code instead — long trailing comments get truncated by editors and ignored by readers.
Block Comments
/* */ is worth reaching for in two cases: a comment that needs more than one line, and a comment that sits in the middle of an expression.
One trap: block comments don't nest. The first */ ends the comment, even if you thought you were still inside an outer one:
/* outer /* inner */ still outer */
// SyntaxError — the first */ closed the block,
// and "still outer */" is now invalid code.
If you need to comment out code that already contains /* */, use // on each line instead.
Commenting Out Code
While you're debugging, you'll often want to temporarily disable a few lines. Both comment forms work:
Every editor has a shortcut for this — Ctrl+/ on Windows/Linux, Cmd+/ on Mac — which toggles // on the selected lines. Learn it once; you'll use it every day.
Commented-out code is meant to be temporary. Don't commit graveyards of dead code with // old version, keep just in case above them. Version control remembers the old code for you. Delete it.
Comment the Why, Not the What
This is the single rule that separates useful comments from noise. The code already shows what it does. A good comment explains why.
Noise:
Those comments don't tell the reader anything the code didn't already say. Compare:
Both comments reference something a reader couldn't figure out from the code alone — an external constraint, a documented quirk. That's the bar. If removing the comment wouldn't leave anyone confused, the comment wasn't pulling its weight.
JSDoc: Comments That Tools Read
JSDoc is a convention for writing block comments that describe functions in a structured way. Editors and type checkers read them and give you better autocomplete and hover docs:
The /** (two stars) opening is what marks it as JSDoc rather than a regular block comment. You don't need JSDoc on every function — it's most worthwhile for public APIs, shared utilities, and anywhere types aren't already obvious from the code.
A Few Habits Worth Keeping
- Keep comments close to the code they describe. A comment ten lines above the relevant line tends to drift out of sync as the code changes.
- Update comments when you change the code. An outdated comment is worse than no comment — it actively lies to the next reader.
- Prefer better names over more comments.
const d = 86400000;needs a comment.const MILLISECONDS_PER_DAY = 86_400_000;doesn't. - Flag temporary issues with
TODO:orFIXME:. Most editors highlight these, and they're easy to grep for later.
A Note on HTML vs JavaScript Comments
If you're writing JavaScript inside an HTML file, don't confuse the two comment styles. HTML uses <!-- -->; JavaScript uses // and /* */. Inside a <script> tag, only the JavaScript forms work:
<script>
// Correct — JS comment inside <script>
/* Also correct */
<!-- Wrong — this is an HTML comment and will break your JS -->
console.log("hi");
</script>
Browsers historically tolerated <!-- --> inside scripts for ancient-browser reasons, but treat it as broken and move on.
Next: Declaring Variables
Now that you can annotate code, it's time to write some. JavaScript has three ways to declare a variable — let, const, and var — and picking the right one is the first real decision you'll make on every line. That's next.
Frequently Asked Questions
How do you write a comment in JavaScript?
Use // for a single-line comment — everything after it on that line is ignored. Use /* ... */ for a block comment that can span multiple lines. Both work anywhere in a .js file and in <script> tags inside HTML.
What's the difference between // and /* */ in JavaScript?
// runs to the end of the current line and stops. /* */ starts at /* and ends at the next */, so it can wrap several lines or sit inline in the middle of an expression. Use // for short notes, /* */ when you need more than one line or want to annotate part of an expression.
How do you comment out a block of code in JavaScript?
Wrap it in /* */, or prefix each line with //. Most editors have a shortcut — Ctrl+/ (Cmd+/ on Mac) toggles // comments on the selected lines. Avoid nesting /* */ inside other /* */ — the first */ closes the outer comment and you'll get a syntax error.
When should I write a comment?
Comment the why, not the what. If the code is doing something non-obvious — a workaround, a business rule, a performance trick — explain why. Don't narrate what the code already says. A well-named variable or function removes the need for most comments.
