Chapter 4 Flashcards — Comments
flashcards clean-code comments
What is the core philosophy of Clean Code toward comments?
?
Comments are a necessary evil at best. The proper use of a comment is to compensate for our failure to express ourselves in code. Before writing a comment, try first to refactor the code so the comment is unnecessary.
Why do comments “lie” over time?
?
Code changes constantly; comments often do not. A comment that was accurate when written becomes misleading as the code evolves. The older a comment, the greater the chance it no longer describes what the code actually does.
What is a “redundant comment” and why is it harmful?
?
A redundant comment restates exactly what the code already says, more slowly. // The day of the month above int dayOfMonth is redundant. It adds no information, creates visual noise, and trains developers to ignore all comments — including the important ones.
What makes a misleading comment more dangerous than no comment at all?
?
A misleading comment is subtly wrong — it says “fires when closed” when it actually fires just before closed. Developers trust comments and write code based on them, so a wrong comment actively introduces bugs. No comment forces developers to read the code; a misleading comment makes them trust a lie.
What is commented-out code, and what should you always do with it?
?
Commented-out code is source code that has been disabled by wrapping it in comment syntax. You should always delete it. It rots (API references break), it scares maintainers (they won’t delete it “in case it was important”), and source control will recover it if it is ever needed again.
What are “mandated comments” and why are they a problem?
?
Mandated comments arise from rules like “every method must have Javadoc.” The result is auto-generated noise: @param name The name. They carry no information, they clutter every class, and they become wrong when signatures change without the comments being updated.
What is a “journal comment” and why should you delete them?
?
A journal comment is a change-log block at the top of a file: who changed it, when, and what they changed. These belong in source control (git log, git blame), not in source code. They are always out of date and clutter the file header.
What is a “closing brace comment” and what does it signal?
?
A closing brace comment looks like } // end of while or } // end of processAllOrders(). It signals that the function is too long — so long that the reader has lost track of which block they are in. The fix is to shorten the function, not add a comment.
What is an “attribution comment” and where should that information live instead?
?
An attribution comment is /* Added by Rick */ or /* Fixed by Fred, 2022-03-14 */. This information belongs in source control (git blame). Attribution comments clutter the code and become incorrect as others modify the same lines.
What is a “position marker” comment and when is it acceptable?
?
A position marker is a banner like /////// Actions /////// that divides sections of a file. Occasional use is tolerable, but overuse trains developers to skip them. Their presence usually signals that a class has too many responsibilities and should be split instead.
What is a “nonlocal information” comment?
?
A comment that describes something distant in the codebase from where the comment is written. For example, a comment above startServer(int port) that describes the default port value defined in a configuration class. When the remote thing changes, the comment here won’t be updated.
What is “too much information” in a comment?
?
A comment that includes historical discussions, RFC history, or interesting but irrelevant context that belongs in a design document or wiki — not in source code. Readers have to wade through it to find the relevant information.
What is an “inobvious connection” comment?
?
A comment where the reader cannot easily connect the comment to the code it describes. For example: /* plus filter bytes and extra 200 bytes for header */ above new byte[(width+1)*height*3+200]. The reader must understand PNG encoding to make the connection, defeating the purpose.
What are “function header” comments and when are they a code smell?
?
A comment at the top of a function that describes what the function does. When the urge to write one arises, it usually means the function name is inadequate. The fix: rename the function so the header comment becomes unnecessary. // Checks if user is active and subscription is valid → rename to isActiveSubscriber().
Name the 8 types of GOOD comments from Clean Code.
?
- Legal (copyright/license), 2. Informative (explains a non-obvious result like a regex), 3. Explanation of Intent (explains WHY a decision was made), 4. Clarification (disambiguates an ambiguous library call), 5. Warning of Consequences (warns about a slow test, destructive op), 6. TODO (tracked, actionable reminders), 7. Amplification (highlights a critical-looking-trivial line), 8. Public API docs (Javadoc/Doxygen on public surfaces).
What is an “explanation of intent” comment and why is it irreplaceable?
?
An explanation of intent comment explains WHY the code does something — the reasoning behind a decision — rather than what it does. Code can show the “what”; it often cannot show the “why.” For example: why a lock-free queue is used in an audio callback instead of std::mutex. These comments are irreplaceable because the reasoning is external context, not derivable from the code.
What is an “amplification” comment and what does it protect against?
?
An amplification comment emphasizes that a line of code which looks trivial is actually critical. For example: // The trim is essential. Leading whitespace would corrupt the next parse stage. It protects against future maintainers “cleaning up” the trim call and introducing a bug.
What is a “warning of consequences” comment? Give a real example.
?
A warning of consequences comment alerts future developers to a non-obvious and potentially costly side effect. Example: // WARNING: This test creates a full 50 GB snapshot. Do NOT run without DBA approval. These comments should never be deleted — they exist because someone learned the hard way.
What is a TODO comment and what policy should govern them?
?
A TODO comment is a // TODO: marker noting work that cannot be done right now. Good TODOs are linked to a tracking ticket and are time-bounded. They should be reviewed and pruned regularly. A TODO without a ticket is noise; one that has been there for years is dead intent.
What is the difference between “informative” and “explanation of intent” comments?
?
Informative comments explain what a result is — e.g., what a regex pattern matches. Explanation of intent comments explain why a particular approach was chosen — e.g., why a lock-free structure was used instead of a mutex. The distinction: informative explains an output; intent explains a decision.
When is Javadoc/Doxygen on a method justified?
?
When the method is part of a public API surface consumed by callers outside the module or library. Javadoc should describe what the method does, its preconditions, what each parameter means, what it returns, and what exceptions it throws. On internal or private methods, Javadoc adds noise without value.
Why is “mandated Javadoc” often worse than no Javadoc at all?
?
Mandated Javadoc on every method produces auto-generated noise like @param order The order that is slower to read than just reading the code. It creates a false sense of documentation, becomes incorrect when signatures change without updating the comment, and wastes review time.
What is the “clarification” comment type? When is it acceptable?
?
A clarification comment explains the meaning of an ambiguous call, magic value, or library method. Acceptable when using a third-party library whose names are outside your control. If you own the API, fix the name instead of adding a comment. Example: // a.compareTo(b) == -1 means a < b.
Why should you prefer refactoring over adding a comment?
?
Every comment is a maintenance liability — it can become wrong, it takes time to read, and it trains readers to ignore comments. Refactoring produces better names, smaller functions, and clearer structure that never goes out of date because it is the code itself. A good name needs no explanation.
What does Clean Code say about HTML in Javadoc comments?
?
HTML in Javadoc source is unreadable by developers in a text editor or IDE source view. Formatting is the responsibility of the documentation generation tool (Javadoc, Doxygen), not the author. Write prose; let the tool render it.
How do you know a comment is “noise”?
?
A comment is noise if removing it leaves the reader with exactly the same understanding of the code. /** Default constructor. */ on an empty constructor adds nothing. The test: does this comment teach the reader something they could not immediately derive from the code and its name?
What is the “legal comment” type and what is the rule for keeping them short?
?
Legal comments are copyright notices and license identifiers at the top of source files, required by company policy or license terms. They are legitimate. The rule: reference an external license document (e.g., // See LICENSE.md) rather than copying all the legal terms inline.
Total Cards: 27
Review Time: ~17 minutes
Priority: HIGH
Last Updated: 2026-04-14