5 exercises on documentation key phrases. Choose the most natural and professional option.
0 / 10 completed
1 / 10
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 / 10
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 / 10
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 / 10
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 / 10
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.
6 / 10
Sarah from the QA team just left a comment on your pull request. She's pointing out that the `calculate_discount` function doesn't handle negative input values, which could lead to unexpected results. Which inline comment would be most appropriate for you to respond with?
Sarah's comment highlights a specific risk – invalid input. The best response directly acknowledges the issue and prompts further action. Option A is irrelevant; Option C misrepresents the situation, and Option D suggests a solution without addressing the core concern.
7 / 10
Mark, the senior developer, has suggested adding a JSDoc comment to your `process_data` function. He wants to clearly state that the function will handle large datasets efficiently. Which of the following options best fulfills this requirement?
Mark is requesting documentation that explains *how* the function performs well. Option A is a generic statement without specifics. Option D is too vague. Option B misrepresents performance guarantees, but option 2 provides a clear description of the parameter's role in efficient data handling – crucial for understanding its purpose.
8 / 10
You're documenting a new API endpoint that returns user profiles. The endpoint uses a unique identifier (`user_id`) to fetch the data. Which JSDoc comment is most appropriate for describing the `user_id` parameter?
The question specifically asks about documenting the `user_id` parameter. Option A is too general; option D is a description of what the ID *represents*, but not how it's used in the API. Option B is accurate but lacks detail on its role as an identifier.
9 / 10
David has left a comment on your code saying: 'This temporary fix for the race condition might not be robust enough. We should investigate a more permanent solution.' Which inline comment would you use to acknowledge his feedback and plan next steps?
David's comment flags potential instability of the temporary fix. The best response acknowledges that concern and indicates a path forward – further investigation and testing. Option A directly addresses his observation about robustness, while Options B and C are too simplistic or focused on specific actions without acknowledging the underlying risk.
10 / 10
Your team is migrating to a new version of your application. You've identified a function that needs to be updated to align with the new API schema. Which comment would you use to mark this function for review after the migration is complete?
The goal is to signal that the function needs attention after the migration. Option A clearly indicates the need for an update due to the new schema. Options B and C are irrelevant; option D suggests testing but doesn't highlight the necessary change.
What will I practise in "Code Documentation: Inline Comments & Doc Phrases"?
This module focuses on Phrasebook — real workplace phrasing you'll use on the job. It contains 10 scenario-based multiple-choice questions with instant feedback.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to use with no account or sign-up required.
How many questions does this exercise have?
This module includes 10 questions. Each one gives an immediate right/wrong result plus a full explanation of the correct phrasing.
What happens if I answer a question incorrectly?
You'll see the correct answer highlighted straight away, along with a plain-English explanation of why it's right and why the other options don't fit — mistakes are part of the learning here.
Can I retry the exercise if I want a better score?
Yes — use the 'Try again' button on the results screen to reset your score and go through the questions again. There's no limit on attempts.
Who is this Phrasebook exercise for?
It's aimed at IT professionals with working English who want to sound more natural and precise around phrasebook — useful whether you're preparing for real conversations at work or just building confidence with the vocabulary.
Do I need an account to track my progress?
No account is needed. Your progress through the exercise is tracked locally in your browser for the current session, and you can replay the module at any time.
How is this different from reading a blog article?
This exercise is an interactive drill that tests and reinforces specific phrasing through multiple-choice questions with instant feedback, while blog articles explain concepts and vocabulary in prose. The two work well together.
Where can I find more Phrasebook exercises?
See the Phrasebook hub for more modules like this one, or browse the full Exercises page for other IT-English topics.
Can I complete this exercise on my phone?
Yes — every exercise on CoderSlingo is fully responsive and works on phones and tablets, so you can practise anywhere.