Practice writing clear, professional code comments in English: verb tense, imperative style, brevity, and avoiding common mistakes.
0 / 8 completed
1 / 8
What verb form is recommended for single-line comments describing what a function does?
Third-person present tense is the standard for function and class docstrings: 'Returns the user by ID', 'Validates the input schema'. It reads as a factual description of what the function does.
2 / 8
What is wrong with this comment? // This function was written to handle edge cases
History-based comments ('was written to...', 'added for the Y feature') rot quickly. The code's git history captures this context better. Comments should describe what the code does or why a non-obvious choice was made.
3 / 8
Which of these is a good inline comment?
The best comments explain the non-obvious WHY: a specific constraint, a surprising limit, a workaround for a known bug. Restating what the code does (increment i, loop through users) adds no value.
4 / 8
What does 'imperative style' mean for docstring summaries?
PEP 257 (Python) recommends imperative style for docstring first lines: 'Do this', 'Return that'. Google style guides and many others agree. It reads like a command to the function: 'Fetch the user record...'
5 / 8
What is a 'TODO comment' and what information should it include?
TODO comments without ownership or context accumulate and are never resolved. Adding an owner, a brief description, and a ticket reference makes them actionable and traceable.
6 / 8
What is wrong with this comment style? // VERY IMPORTANT!!! Do not remove this line!!!
Shouting comments ('VERY IMPORTANT!!!') create alarm without explanation. Better: '// Required for CORS preflight — removing breaks cross-origin requests from the React app (see TICKET-456)'. The reason is what matters.
7 / 8
When should a comment NOT be written?
The worst comment is one that repeats what clear code already says. 'getUserById(id)' is self-documenting. Comments should add information the reader cannot derive from the code itself.
8 / 8
What is the correct way to write a deprecation notice in a code comment?
A useful deprecation comment names the replacement, states the version of removal, and links to a migration guide. This gives developers everything they need to migrate without searching for context.