Reading Code Comments

"skip header row" — the comment explains WHY we start at 1 instead of 0. This is a good comment because it explains intent, not just mechanics.

Reading comments effectively means asking: "What does this tell me about the code's purpose?"

• // skip header row → explains WHY (the array position 0 is headers, not data)
• Compare with a bad comment: i = 1; // set i to 1 — this only restates the code without adding information

Good comments in code answer:
• WHY is this value chosen? ("1" not "0" because position 0 is a header)
• WHY is this approach used? ("use polling, not webhooks, because vendor doesn't support webhooks")
• WHY does this edge case exist? ("exclude negative values — the API returns -1 for unknown age")

TODO — a conventional marker meaning "this functionality is planned but not yet implemented".

Standard comment markers:
• TODO: — work remaining; should be done eventually. "TODO: refactor this into a shared utility"
• FIXME: — known bug or incorrect behavior. "FIXME: race condition when two requests arrive simultaneously"
• HACK: / XXX: — temporary workaround; should be revisited. "HACK: hardcoded timeout, replace with config"
• NOTE: / NB: — important information a reader must know. "NOTE: this function mutates the input array"
• DEPRECATED: — function/method should no longer be used. "DEPRECATED: use getUserById() instead"

Many teams use a linter or IDE plugin (e.g., "TODO Highlight" in VS Code) to make these markers visible in the problems panel.

@param {string} recipient — required parameter (no square brackets)
@param {boolean} [urgent=false] — optional parameter (square brackets = optional in JSDoc)

JSDoc @param syntax:
• @param {"{type}"} name - description — required parameter
• @param {"{type}"} [name] - description — optional, no default
• @param {"{type}"} [name=default] - description — optional with a default value

Reading JSDoc:
• Type in curly braces: {"{string}"}, {"{number}"}, {"{boolean}"}, {"{Object}"}, {"{Array.<string>}"}
• Square brackets = optional
• =false inside square brackets = default value

This pattern is used by JSDoc, TypeDoc, and similar tools to generate API documentation from source code comments.

@returns {"{Promise}"} — documents the return type and meaning:

• Promise — the function is asynchronous; you need to await it or chain .then()
• User | null — TypeScript union: the resolved value is either a User object or null
• null if not found — an explicit note that null is a valid "not found" signal, not an error

Reading return type annotations:
• {"{void}"} — returns nothing (side-effect-only function)
• {"{boolean}"} — returns true/false
• {"{Promise}"} — async, resolves with a string
• {"{string[]}"} — array of strings
• {"{Object}"} — generic object (usually means the docs could be more specific)

When you see User | null as a return type in real docs or TypeScript, always check: does the calling code handle the null case? Missing null checks are a frequent source of runtime errors.

O(n²) → O(1) with a hash map — the FIXME explains a known performance problem and proposes a solution.

Reading performance comments:
• O(n²) — "Big O n-squared" — time grows quadratically (nested loops over the same collection). Bad for large n.
• O(n) — linear; acceptable for most cases
• O(1) — constant; independent of input size (hash map lookup, array index access)
• O(log n) — logarithmic; binary search, balanced tree operations

Vocabulary for performance comments:
• "this is a hot path" — frequently executed code, optimisation matters here
• "not on the critical path" — performance not critical here
• "scales poorly" — performance degrades with more data/users
• "linear scan" → should be "indexed lookup"

The FIXME marker signals: this code works but is known to be suboptimal; someone should fix it before it becomes a problem at scale.

Not thread-safe — the module's internal state can be corrupted if multiple threads call it simultaneously.

"Calls must be serialised by the caller" means: your code must ensure only one thread/coroutine calls this at a time. This is a critical architectural constraint communicated through a comment.

Key vocabulary:
• thread-safe — safe to call from multiple threads simultaneously without corruption
• not thread-safe — calls must not overlap; use a mutex, lock, or queue to serialize access
• serialised (in concurrency context) — made sequential, one after another
• serialised (in data context) — converted to a transmissible format (JSON, etc.)
The same word has different meanings depending on context. Here, "serialised by the caller" = made sequential, not JSON.

• race condition — bug that occurs when outcome depends on thread execution order
• mutex / lock — mechanism to allow only one thread at a time
• atomic operation — cannot be interrupted; always completes fully as one unit

NB = nota bene (Latin: "note well") — used for critical warnings that must not be missed.