6 exercises — understand inline comments, TODO/FIXME markers, and JSDoc blocks you encounter in real codebases.
0 / 6 completed
1 / 6
Read this inline comment and choose what it means:
`i = 1; // skip header row`
"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")
2 / 6
What does this comment marker tell a developer?
`// TODO: add retry logic for transient network errors`
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.
3 / 6
Read this JSDoc comment and identify what the @param line documents:
```
/**
* Sends an email notification.
* @param {string} recipient - The email address of the recipient.
* @param {boolean} [urgent=false] - If true, send with high priority flag.
*/
```
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.
4 / 6
What does this @returns tag document?
`@returns {Promise} the user object, or null if not found`
@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.
5 / 6
A developer reads this comment:
`// FIXME: this is O(n²) — replace with hash map lookup for large datasets`
What is the issue and what is the suggested fix?
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.
6 / 6
A developer sees this at the top of a module:
`// NB: This module is NOT thread-safe. All calls must be serialised by the caller.`
What should another developer do when using this module?
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.