Comments Code Smell — Detection & Refactoring

What is the "Comments" Smell?

A Comments smell occurs when a method, class, or block is filled with explanatory comments — not because the logic is genuinely complex, but because the code structure itself is unclear. Comments in this context act like a deodorant: they mask fishy code rather than fixing it.

"A comment is a sign that the code is not finished." — XP community principle

"The best comment is a good name for a method or class."

Comments are not inherently bad — but when they're needed to explain what the code does (rather than why a design decision was made), that's a signal to refactor.

How to Detect It