JAVASCRIPT / GETTING STARTED
Comments and code readability habits
You can write both JavaScript comment forms, predict exactly what the engine discards, and use comments and naming so a file explains its own decisions.
What you will learn
- Write // and /* */ comments and know the tokenizer strips both before anything runs
- Explain why a line exists and let variable names carry what the value is
- Disable code with one // per line so a stray */ cannot close the comment early
- Tell when // starts a comment and when it is just characters inside a string
Understanding Comments and code readability habits
JavaScript has two comment forms. A // discards everything from those two characters to the end of that line, and /* */ discards everything between the markers, line breaks included. Both are handled by the tokenizer, the stage that chops your text into tokens, so by the time any expression is evaluated the comment no longer exists; a block comment sitting between two tokens counts as nothing more than a space. That is why a comment cannot crash a program or alter a value, and why its only possible failure is misleading the person reading it.
The model worth keeping is that a file has two readers with different needs: the engine and a human. The code already states what happens step by step, and good names state what the values are, so prose repeating either one is duplicated information that goes stale on the first edit, and a stale comment is worse than no comment because readers trust it. Comments earn their place when they carry what the code physically cannot say: the unit a number is in, the reason a strange-looking line is required, the bug it works around, the option you rejected.
The readability habits follow from that split. When you feel the urge to write a comment, try renaming first: delay becomes delayMs, p becomes pricePerSeat, and the comment vanishes because the line now reads on its own. When you silence code while hunting a bug, comment the lines out with // and delete them once the bug is found, since version control already remembers the old version and a commented-out block only forces the next reader to guess which version is live.
// Money is kept in whole cents: 19.99 * 100 does not land exactly on 1999,
// so every conversion has to round instead of trusting the multiplication.
function toCents(dollarAmount) {
return Math.round(dollarAmount * 100);
}
console.log(toCents(19.99));
console.log(19.99 * 100); // the value the comment above is warning about
console.log(0.1 + 0.2 === 0.3); /* same cause, different symptom */Comments are removed before your program runs, so their only job is to tell a human something the code itself cannot say, which is usually why.
Worked examples
Two slashes inside a string are not a comment
Shows that whichever delimiter opens first decides how the rest of the line is read.
const docsUrl = "https://developer.example.com/guide"; // where the format is defined
console.log(docsUrl);
console.log(docsUrl.indexOf("//"));Example explained
Line 1The opening quote comes first, so the // at index 6 is ordinary string data with no special meaning.
Line 2The // after the semicolon sits outside any string, so the rest of that line is thrown away before evaluation.
Line 3indexOf reports 6, proving the string kept every character the comment marker would otherwise have eaten.
Switching lines off while debugging
Demonstrates why one line comment per line is the safe way to disable code.
const items = ["pen", "mug"];
// items.push("hat"); /* left over from yesterday's debugging */
// console.log("count:", items.length);
console.log(items.join(", "));Example explained
Line 1Each // disables exactly one line, so push never runs and the array still holds two entries.
Line 2The /* */ on the first disabled line is inert: the // already claimed everything up to the line break, so that */ closes nothing.
Line 3Nothing inside a line can terminate a line comment early, which is what makes this safer than wrapping the block in /* */.
A documentation comment the engine ignores
Shows that JSDoc tags are editor food, not runtime rules.
/**
* Keep a value inside an inclusive range.
* @param {number} value
* @param {number} min
* @param {number} max
* @returns {number}
*/
function clamp(value, min, max) {
return Math.min(Math.max(value, min), max);
}
console.log(clamp(42, 0, 10));
console.log(clamp("7", 0, 10));Example explained
Line 1/** opens an ordinary block comment; the extra asterisk is a convention editors and doc tools look for, not something the engine understands.
Line 2The @param tags let an editor show parameter hints while you type, keeping the description next to the function instead of in a separate file.
Line 3The second call passes the string "7" and still returns 7, because Math.max coerces it and no tag is ever checked at runtime.
Important notes
Block comments do not nest: the first */ closes the comment however many /* preceded it, so /* a /* b */ c */ leaves c */ behind as code and fails to parse.
Inside an HTML script element the HTML parser scans for the closing tag before JavaScript is ever parsed, so a </script> written inside a JavaScript comment still ends the script block; break it up as <\/script> if you need to mention it.
Common mistakes
Wrapping code in /* */ when that code already contains */, whether inside a string like "*/", a regular expression, or an older block comment. The comment ends at that first */ and the leftover characters are parsed as code, producing a SyntaxError on a line you believed was disabled.
Changing the code but not the comment above it, so a note claiming three retries sits over maxRetries = 5. The next reader believes the prose, reasons from the wrong number, and reports a bug against code that works.
Keeping large commented-out blocks just in case. Nobody can tell which version is live, and someone eventually re-enables a block that calls functions no longer in the file.
Try it yourself
Change, predict, then run
In a browser editor write const p = 1999; // cents, not dollars followed by a line logging p / 100, then rename p so the comment is redundant, delete the comment, and confirm the console still logs 19.99.
Open the JavaScript workspaceCheck your understanding
Why do experienced developers prefer comments explaining why a line exists over comments restating what it does?
- Comments are evaluated while the script runs, so shorter comments make it measurably faster.
- A comment restating the line duplicates information, so the first edit to the code leaves behind a comment that lies to the next reader.
- Only /* */ comments are stripped by the engine, while // comments stay in memory during execution.
- The engine prints a console warning when a comment no longer matches the code beneath it.
Show answer
Restating code stores the same fact twice, and the copy in prose is the one nobody updates, so it drifts into being false while still looking authoritative. The performance option is tempting because comment length does affect how many bytes a browser downloads, but comments are discarded by the tokenizer before any evaluation happens, so they cost nothing at run time, and the engine never compares a comment against the code.