6 exercises — spot anti-patterns (lying comments, obvious comments, journal comments, commented-out code) and rewrite them to high standard.
0 / 19 completed
1 / 19
Identify the anti-pattern in this comment:
`x = x + 1; // add 1 to x`
Obvious comment — the most common comment anti-pattern. The comment adds no value; anyone who can read code already knows x = x + 1 adds 1 to x.
Fix: either delete the comment, or replace it with a WHY comment: • x = x + 1; // advance past the BOM character at offset 0 • x = x + 1; // skip index 0 — reserved for the null sentinel value
Comment quality anti-patterns: 1. Obvious comment: restates the code ("add 1 to x") 2. Lying comment: describes different behavior than what the code does 3. Journal comment: "Added by Alex on 2023-07-14" — use git blame instead 4. Commented-out code: dead code left in the file — delete it, git history preserves it 5. Noise comment: empty, placeholder, or meaningless ("TODO: fix later")
When code is well-named and obvious, no comment is the best comment.
2 / 19
You find this in a codebase:
```
// Validates the user input
function processPayment(amount, card) {
charge(card, amount * 1.2);
}
```
What type of comment problem is this?
Lying comment — the most dangerous comment anti-pattern. The comment says "Validates the user input" but the function actually charges the card (and applies a 1.2× multiplier — possibly undocumented tax or fee).
Lying comments cause bugs because developers trust comments over code when they conflict. A developer might rely on "validates input" without reading the implementation, leading to double-charging, missing validation, or both.
How lying comments happen: • Code was changed after the comment was written, but the comment was not updated • Comment was copied from another function • Developer described intent rather than actual behavior
Fix: 1. Delete the lying comment 2. If validation is needed, add it (the comment may describe a missing requirement) 3. Write an accurate comment: "// Charges the card amount plus 20% tax and fee surcharge"
Rule: if you change code that has a comment above it, you MUST update or delete the comment.
3 / 19
A developer left this in the codebase:
```
// Alex, 2022-03-15: added cache layer
// Alex, 2022-04-02: added TTL config
// James, 2022-06-11: fixed memory leak in eviction
```
What is the problem with these comments?
Journal / changelog comments — an anti-pattern that pollutes source code with information that git already tracks far better.
Problems: • Git blame and git log already record who changed what, when, and why (in the commit message) • These comments grow over time until they exceed the actual code in length • They are never kept fully up to date • They add noise when reading the code
What to do instead: • Write meaningful commit messages: "fix: resolve memory leak in cache eviction (see #891)" • Use git blame to see who last changed each line • Use git log --follow -p -- src/cache.js to see full file history • Reference ticket/issue numbers in commit messages for traceability
The only time author+date in code is acceptable: legal/licence headers required by open-source licences, or regulatory environments where source-level audit trails are mandated by external compliance requirements.
4 / 19
You encounter a function with 30 lines of commented-out code. What is the best action?
Delete it — commented-out code is one of the clearest code smell anti-patterns.
Why delete, not keep: • Git history preserves the code — use git log or git show <commit> to retrieve it anytime • Commented-out code creates confusion: "Is this intentionally disabled? Is it a WIP? Is it broken?" • It adds noise to every code review, every search, every refactor • Over time, commented-out code becomes so stale it would need rewriting anyway
When you are about to comment out code, ask: • "Am I going to need this again?" → If yes, keep it in a feature branch • "Is this a WIP?" → Use a WIP commit in Git, not commented-out code • "Should I preserve this?" → Already in git history
The only acceptable commented-out code: • A // TODO: uncomment when feature X ships for a very short time frame, with a linked issue • Example code in docs/comments that should NOT be run automatically
5 / 19
Rewrite this poor quality comment to follow best practices:
`// This is important`
(above a JWT verification step)
Option B transforms a vague "important" into an actionable security note that tells developers:
1. What this does: "all requests must pass this point" — establishes the scope 2. The explicit warning: "DO NOT bypass" — direct instruction 3. The consequence: "skipping JWT verification exposes all endpoints to anonymous access" — makes the risk concrete
"This is important" is a noise comment because: • "Important" is relative and undefined • It gives no guidance on what would happen if this was changed • A future developer has no idea WHAT is important about it
Rewriting bad comments — the process: 1. Ask: WHY is this important? What constraint does it represent? 2. Ask: What would break if this was removed or changed? 3. Write: statement of constraint + DO NOT + consequence of violating it
Pattern: // NOTE: [what this is] — [explicit warning] — [consequence of changing it]
6 / 19
Which of these is the ONLY situation where a high volume of detailed comments is justified?
Non-obvious algorithms — the primary legitimate use case for dense commenting.
Examples where line-by-line commenting is genuinely valuable: • Cryptographic algorithms (each step has a security reason) • Bitwise operations and bit manipulation tricks • Cache-oblivious algorithms, SIMD optimisations • State machine with subtle transition logic • Numerical methods with convergence conditions • Regex patterns that span multiple lines
Good algorithm comment example:
// Murmur3 hash finalisation mix
// Avalanche bits to ensure uniform distribution
// (see Appleby 2011, "MurmurHash3")
x ^= x >> 16;
x *= 0x85ebca6b; // magic constant — provides good bit mixing
x ^= x >> 13;
x *= 0xc2b2ae35; // second mixing constant
x ^= x >> 16;
The test: if a competent colleague would understand the code without a comment in 30 seconds, the comment is probably not needed. If it would take 10 minutes and a whiteboard, write the comment.
7 / 19
During a code review for a new API endpoint, Sarah points out this comment in the PR description:
`// This handles authentication. Pretty self-explanatory, right?`
David responds with: `Sounds good, thanks Sarah!`
What's the primary issue with Sarah's comment and David's response, from a code review perspective?
insufficient — the account balance is too low...
the comment doesn't provide enough context for someone unfamiliar with the authentication process.
it's overly verbose and adds unnecessary detail to the PR description.
David's response doesn't address Sarah's concern effectively, simply acknowledging it without further discussion.
The core problem isn't just that the comment is 'self-explanatory'; a good code review should consider developers who *aren't* familiar with the specific authentication logic. A helpful comment describes *why* something is done and its purpose within the broader system. David's response fails to engage with Sarah's feedback, failing to ask clarifying questions or offer additional information – this is a missed opportunity for improving understanding during the review.
8 / 19
Scenario
You're reviewing a pull request for a new payment processing service. The developer has added this comment to the `processPayment` function:
// Validates the user input
function processPayment(amount, card) {
charge(card, amount * 1.2);
}
During the code review, your team lead asks you to explain why this comment is problematic. Which of the following best describes the issue?
The comment '// Validates the user input' is insufficient because it doesn't explain *how* the input is validated. This leaves reviewers unsure of what checks are being performed and whether they are adequate. The correct answer highlights that this comment lacks crucial context regarding the validation process itself – a key element for understanding the function's behavior and potential vulnerabilities. Options B, C, and D represent misinterpretations or tangential concerns about David's response rather than directly addressing the core issue with the comment.
9 / 19
During a code review for a new API endpoint, Sarah points out this comment in the PR description:
`// This handles authentication. Pretty self-explanatory, right?`
David responds with: `Sounds good, thanks Sarah!`
What's the primary issue with Sarah's comment and David's response, from a code review perspective?
insufficient — the account balance is too low...
the comment doesn't provide enough context for someone unfamiliar with the authentication process.
it's overly verbose and adds unnecessary detail to the PR description.
David's response doesn't address Sarah's concern effectively, simply acknowledging it without further discussion.
The core problem isn't just that the comment is 'self-explanatory'; a good code review should consider developers who *aren't* familiar with the specific authentication logic. A helpful comment describes *why* something is done and its purpose within the broader system. David's response fails to engage with Sarah's feedback, failing to ask clarifying questions or offer additional information – this is a missed opportunity for improving understanding during the review.
10 / 19
Scenario
You're reviewing a pull request for a new payment processing service. The developer has added this comment to the `processPayment` function:
// Validates the user input
function processPayment(amount, card) {
charge(card, amount * 1.2);
}
During the code review, your team lead asks you to explain why this comment is problematic. Which of the following best describes the issue?
The comment '// Validates the user input' is insufficient because it doesn't explain *how* the input is validated. This leaves reviewers unsure of what checks are being performed and whether they are adequate. The correct answer highlights that this comment lacks crucial context regarding the validation process itself – a key element for understanding the function's behavior and potential vulnerabilities. Options B, C, and D represent misinterpretations or tangential concerns about David's response rather than directly addressing the core issue with the comment.
11 / 19
During a code review for a new API endpoint, Sarah points out this comment in the PR description:
`// This handles authentication. Pretty self-explanatory, right?`
David responds with: `Sounds good, thanks Sarah!`
What's the primary issue with Sarah's comment and David's response, from a code review perspective?
insufficient — the account balance is too low...
the comment doesn't provide enough context for someone unfamiliar with the authentication process.
it's overly verbose and adds unnecessary detail to the PR description.
David's response doesn't address Sarah's concern effectively, simply acknowledging it without further discussion.
The core problem isn't just that the comment is 'self-explanatory'; a good code review should consider developers who *aren't* familiar with the specific authentication logic. A helpful comment describes *why* something is done and its purpose within the broader system. David's response fails to engage with Sarah's feedback, failing to ask clarifying questions or offer additional information – this is a missed opportunity for improving understanding during the review.
12 / 19
Scenario
You're reviewing a pull request for a new payment processing service. The developer has added this comment to the `processPayment` function:
// Validates the user input
function processPayment(amount, card) {
charge(card, amount * 1.2);
}
During the code review, your team lead asks you to explain why this comment is problematic. Which of the following best describes the issue?
The comment '// Validates the user input' is insufficient because it doesn't explain *how* the input is validated. This leaves reviewers unsure of what checks are being performed and whether they are adequate. The correct answer highlights that this comment lacks crucial context regarding the validation process itself – a key element for understanding the function's behavior and potential vulnerabilities. Options B, C, and D represent misinterpretations or tangential concerns about David's response rather than directly addressing the core issue with the comment.
13 / 19
During a code review for a new API endpoint, Sarah points out this comment in the PR description:
`// This handles authentication. Pretty self-explanatory, right?`
David responds with: `Sounds good, thanks Sarah!`
What's the primary issue with Sarah's comment and David's response, from a code review perspective?
insufficient — the account balance is too low...
the comment doesn't provide enough context for someone unfamiliar with the authentication process.
it's overly verbose and adds unnecessary detail to the PR description.
David's response doesn't address Sarah's concern effectively, simply acknowledging it without further discussion.
The core problem isn't just that the comment is 'self-explanatory'; a good code review should consider developers who *aren't* familiar with the specific authentication logic. A helpful comment describes *why* something is done and its purpose within the broader system. David's response fails to engage with Sarah's feedback, failing to ask clarifying questions or offer additional information – this is a missed opportunity for improving understanding during the review.
14 / 19
Scenario
You're reviewing a pull request for a new payment processing service. The developer has added this comment to the `processPayment` function:
// Validates the user input
function processPayment(amount, card) {
charge(card, amount * 1.2);
}
During the code review, your team lead asks you to explain why this comment is problematic. Which of the following best describes the issue?
The comment '// Validates the user input' is insufficient because it doesn't explain *how* the input is validated. This leaves reviewers unsure of what checks are being performed and whether they are adequate. The correct answer highlights that this comment lacks crucial context regarding the validation process itself – a key element for understanding the function's behavior and potential vulnerabilities. Options B, C, and D represent misinterpretations or tangential concerns about David's response rather than directly addressing the core issue with the comment.
15 / 19
During a Slack discussion about a complex data transformation function, Mark says: 'Just add a comment explaining what it does. It's obvious!' Emily replies with a GIF of rolling her eyes. What is the primary issue with Mark's statement?
The core issue isn't about the *presence* of comments, but their quality. Mark's statement suggests a belief that 'obviousness' justifies insufficient explanation. Good comments clarify intent, potential pitfalls, and assumptions—something an 'obvious' function may not immediately convey to someone unfamiliar with the code or its context. Emily's reaction highlights this disconnect.
16 / 19
You're reviewing a PR for a new microservice that handles user profiles. The developer has added the following comment to the `getUserById` function:
```
// Returns user data based on ID.
return user;
```
What is the most appropriate response in your code review?
While the comment *technically* describes what the function does, it doesn't provide enough context. The ideal response encourages further clarification of potential edge cases – specifically, what happens if no user is found by ID. This demonstrates a focus on robustness and error handling, which are crucial for reliable services. The other options either miss this point or offer overly simplistic advice.
17 / 19
During a standup meeting, David says: 'I've added a comment explaining the caching strategy in the `getProducts` function.' The team lead asks, 'Why is that necessary? We have documentation for this.' What's the *best* response from David?
David's response correctly identifies that the comment fills a gap between documentation and the actual code. The caching strategy might not be immediately obvious from reading the code, especially for someone unfamiliar with the system. Highlighting this difference is key – comments aren't replacements for documentation but supplements to make complex logic more accessible at a glance.
18 / 19
A developer submits a PR with the following comment:
```
// This function handles data validation.
validateData(data);
```
You are reviewing this. Which statement best describes the problem?
The comment lacks crucial details – it doesn't specify *what* criteria are used for validation or what constitutes valid data. A good comment should explain *how* something works, not just *that* it does. Simply stating the function's purpose is insufficient; it needs to provide context and clarify expectations.
19 / 19
You are reviewing a large codebase where several developers have been contributing. You find many comments that simply state: 'Fixed bug'. What is the *most* important thing to address?
While brevity is valued, 'Fixed bug' comments lack context and don't contribute meaningfully to future maintenance or understanding. The goal should be to guide developers towards providing *why* the bug was fixed – the root cause, the affected areas of code, and any potential side effects. This creates a much more valuable knowledge base for the project.
What will I practice in "Comment Quality — Code Comments Exercises"?
This is a Code Comments exercise set. It walks through 19 scenario-based multiple-choice questions built around real usage of Code Comments terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 19 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the Code Comments vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more Code Comments exercises?
See the Code Comments exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — Code Comments vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.