Comments as Deodorant is a code smell where developers use comments to explain, justify, or apologize for code that is complex, unclear, or poorly structured — applying documentation as a bandage over design problems instead of fixing the underlying issues, producing code where the comment reveals that the code itself needs refactoring, and perpetuating the misconception that a well-commented mess is equivalent to clean code.
What Is Comments as Deodorant?
The smell occurs when comments exist because the code cannot speak for itself:
- Decoding Comments:
// Check if user has paid and is not admin and subscription is active→if (u.p && !u.a && u.s.isActive())— the comment exists because the variable names and logic are unreadable. The fix is readable naming:if (user.hasPaid() && !user.isAdmin() && user.hasActiveSubscription()). - Algorithm Apology:
// This is complex but necessary for performancefollowed by 80 lines of barely readable optimization — the comment acknowledges the problem without solving it. - Magic Number Explanation:
// 86400 seconds in a day— the fix isSECONDS_PER_DAY = 86400. - Step-by-Step Narration: Comments that describe what each line does rather than why the logic exists at all — indicating that the code is not self-explanatory at the intent level.
- Dead Code Comments:
// TODO: refactor this someday— a comment that has lived for 3 years while the code it describes has been refactored multiple times around it.
Why Comments as Deodorant Matters
- Comments Lie, Code Does Not: Code is always true — it does exactly what it does. Comments are not executed and are not tested. As code evolves through refactoring, comments that were accurate when written become stale, misleading, or outright incorrect. A comment that says "returns the user's primary email" on a method that actually returns the first verified email is more dangerous than no comment — it actively misleads.
- Maintenance Multiplier: Every comment introduces a parallel maintenance burden. The logic must be maintained AND the description of the logic must be maintained. In practice, comments are maintained far less diligently than code, creating divergence that accumulates over time.
- Masking the Root Cause: Using comments to explain bad code leaves the bad code in place. The developer has acknowledged the complexity and moved on. Future developers read the comment, nod in understanding, and also leave the bad code in place. The comment perpetuates the problem by reducing the discomfort that would motivate refactoring.
- False Confidence: Teams that measure documentation quality by comment density may feel their codebase is well-maintained based on high comment volume, while the actual code quality deteriorates. Comment density is a poor proxy for code quality.
- Cognitive Double Work: Reading a function with step-by-step narrative comments requires reading both the comments and the code — double the cognitive work of reading clean self-documenting code that needs no commentary.
Good Comments vs. Bad Comments
Not all comments are deodorant. The distinction is what the comment adds:
| Comment Type | Example | Good or Smell? |
|---|---|---|
| Why (intent) | // Retry 3x to handle transient network failures | Good — explains reasoning |
| Warning | // Thread-unsafe — must be called from synchronized block | Good — non-obvious constraint |
| Legal/Regulatory | // Required by GDPR Article 17 | Good — external mandate |
| What (narration) | // Loop through users and check their status | Smell — code should say this |
| Decoder | // x is the user ID, y is the product ID | Smell — use good variable names |
| Apology | // I know this is complicated but... | Smell — fix the complexity |
Refactoring Approaches
Extract Method with Descriptive Name: Replace a commented block with a named method:
// Validate user credentials and check account status→validateUserAndCheckAccountStatus()
Rename Variables/Methods: Replace cryptic names with descriptive ones, eliminating the need for decoding comments.
Introduce Constants: Replace magic numbers with named constants, eliminating explanation comments.
Extract Variable: Introduce well-named intermediate variables that make complex boolean logic readable without comments.
Tools
- SonarQube: Rules for detecting commented-out code blocks, TODO density, and comment-to-code ratios.
- PMD:
CommentDefaultAccessModifier,CommentRequiredrules that enforce comment standards. - CodeNarc (Groovy): Comment quality rules.
- Manual Review: The most effective detector — when reading a comment, ask "Would I need this comment if the code were named better?"
Comments as Deodorant is apologetic coding — the practice of writing explanations for design failures instead of fixing the failures themselves, producing codebases that smell better on the surface while the underlying structural problems accumulate, leaving every future developer to read both the apology and the mess it was written to excuse.
Explore 500+ Semiconductor & AI Topics
From EUV lithography to CUDA optimization — search the full knowledge base or chat with our AI assistant.