5 exercises on documentation key phrases. Choose the most natural and professional option.
0 / 5 completed
1 / 5
Which comment correctly marks a piece of code that must be cleaned up after a major version migration?
"// TODO: remove after v3 migration" is the correct choice. TODO is the universal convention for marking intentional future work — code that is temporarily present but needs action later. Most IDEs and linters highlight TODOs and can list them for review. FIXME signals something is broken right now and needs urgent attention, which is not the case here. HACK means the approach is non-ideal for reasons beyond just cleanup. NOTE is informational and doesn't signal required action. Use TODO whenever there is a specific, actionable future task tied to the code.
2 / 5
A developer has written a temporary fix for a concurrency bug that is known to fail under edge cases. Which comment type is most appropriate?
"// FIXME: this is a workaround for..." is the right tag here. FIXME signals that the code is known to be incorrect or fragile and must be fixed — not merely cleaned up, but actively repaired. A workaround for a concurrency bug that fails under edge cases is exactly this scenario. TODO implies future work on something that currently works acceptably. NOTE is non-actionable — it describes without flagging urgency. DEPRECATED applies to APIs or functions being phased out, not to broken workarounds. FIXME is the strongest urgency signal in comment conventions.
3 / 5
A developer wants to explain that an unusual algorithmic choice is intentional to avoid a known performance trap. Which comment tag is most appropriate?
"// NOTE: this is intentional because..." is the correct convention. NOTE (sometimes written NB:) is used for important contextual information that future maintainers must not miss — especially when the code looks wrong but isn't. It prevents well-meaning developers from "fixing" code that is deliberately unconventional. TODO suggests action is needed; there is none here. FIXME implies the code is broken; it isn't. HACK implies the solution is inelegant and should be replaced, which contradicts the "intentional" framing. NOTE is the correct choice for "don't touch this, here's why."
4 / 5
Which JSDoc comment correctly documents a function parameter named id that holds a unique identifier?
"/** @param id - the unique identifier */" is the correct modern JSDoc syntax for TypeScript projects. When types are inferred from TypeScript, the @param tag uses the parameter name followed by a dash (-) and then the description. This is the TSDoc convention widely used in TypeScript codebases. Option A omits the dash separator, which is technically parseable but not idiomatic. Option B wraps the name in curly braces — in JSDoc that position is for the type, not the name (e.g., @param {string} id). Option C uses parentheses, which is not valid in any JSDoc or TSDoc standard.
5 / 5
A public API method is being replaced by a newer version. Which comment correctly marks the old method for removal?
"Deprecated: use newMethod() instead." is the standard deprecation notice. In JSDoc it appears as @deprecated Use newMethod() instead. inside a doc comment block, but the phrase "Deprecated:" followed by the replacement is the recognised pattern across all documentation systems (JavaDoc, JSDoc, Python docstrings, XML comments). It signals to consumers: "this still works, but stop using it." Option B (TODO) suggests internal cleanup work, not an API-level deprecation notice for external users. Options C and D ("REMOVE", "OLD") are non-standard tags that most tooling will not recognise or surface in IDE hover documentation.