Comments (as Smell): What It Costs and How to Fix It
Excessive comments that compensate for unclear code instead of the code being rewritten to be self-explanatory.
What It Is
The Comments smell does not mean all comments are bad. Useful comments explain why (business reasons, workarounds for platform bugs, legal requirements). The smell refers to comments that explain what the code does, which indicates the code is too complex to understand on its own. When a developer writes a paragraph explaining a 20-line block, the real solution is to extract that block into a well-named method, not to add a comment. Comments that explain 'what' tend to drift out of sync with the code as the code changes but the comment does not.
Why It Costs Money
Stale comments are actively harmful. When a comment says the code does X but the code actually does Y (because the code was changed after the comment was written), the comment misleads developers. Stale comments cause developers to make incorrect assumptions, introducing bugs.
Comments that explain 'what' mask the underlying smell. The code is complex enough to need explanation, but instead of simplifying the code, the team adds comments. The complexity cost remains; the comment is a bandage, not a fix.
Comment maintenance is a hidden cost. Every code change should theoretically update related comments, but in practice comments are rarely updated. This means the comment maintenance either does not happen (creating stale comments) or does happen (adding to every change's effort).
Specific Cost Mechanisms
- ●Stale comment misdirection: each incident costs 1-4 hours when a developer acts on incorrect information
- ●Masked complexity: the underlying code smell continues to cost while the comment creates an illusion of clarity
- ●Maintenance overhead: diligent teams spend 10-15 minutes per PR updating comments
Estimated Annual Cost
Cost per instance by team size and codebase size. Based on $120,000 average developer salary. See full methodology.
| Team Size | Small (<50k LOC) | Medium (50k-200k) | Large (200k+) |
|---|---|---|---|
| 3 devs | $400 | $900 | $1,800 |
| 5 devs | $600 | $1,500 | $3,000 |
| 10 devs | $1,000 | $2,250 | $3,000 |
| 20 devs | $1,200 | $3,000 | $3,000 |
How to Detect It
Specific rules and thresholds for automated detection. See full tool comparison.
Commented-out code, TODO/FIXME comments
Flags TODO/FIXME/HACK comments
Look for comments that describe what the next 5+ lines do
Comment-to-code ratio analysis
Refactoring Patterns
Proven techniques to eliminate this smell. See all refactoring patterns.
Extract Method
A comment describes what a block of code does
Rename Variable/Method
Comments explain what a variable or method represents
Introduce Assertion
A comment describes an expected condition