DispensablesLow

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.

Model cost, team of 8$2K-$6K/yr
Severity
1/5
CategoryDispensables
Detection4 tools

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.

Threshold: Comments that start with 'this does...' or 'the following code...' are smell indicators. Comments that explain 'why' (business rules, platform quirks) are valuable and should be kept.

Why It Costs Money

1

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.

2

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.

3

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: 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: keeping comments in step with the code adds work to every PR

Estimated Annual Cost

Cost of one instance a year by team size, from our model at $180K fully-loaded cost per engineer. Low and high use the bottom and top of the Low inputs; mid is halfway. See full methodology.

Team SizeLowMidHigh
3 devs$700$2K$3K
5 devs$1K$3K$4K
8 devs$2K$4K$6K
10 devs$2K$5K$7K
20 devs$5K$9K$14K

These are model outputs, not measurements. Every input is on the cost model page, and the same model produces the figures on the 22 smells page. Put in your own team and cost in the smell profile calculator.

How to Detect It

Specific rules and thresholds for automated detection. See full tool comparison.

SonarQube
squid:S125 / squid:CommentedOutCodeLine

Commented-out code, TODO/FIXME comments

ESLint
no-warning-comments / spaced-comment

Flags TODO/FIXME/HACK comments

Manual
Code review

Look for comments that describe what the next 5+ lines do

Better Code Hub
Write Clean Code

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

Effort (our estimate): 15-30 minutes
Impact: The method name replaces the comment, and the name stays in sync automatically

Rename Variable/Method

Comments explain what a variable or method represents

Effort (our estimate): 5-15 minutes
Impact: Self-documenting names eliminate the need for explanatory comments

Introduce Assertion

A comment describes an expected condition

Effort (our estimate): 5-10 minutes
Impact: The assertion is checked at runtime, unlike a comment

Related Smells

Updated November 2026