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.

"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

Look for these patterns:

A comment above a block of code that says what the block does → candidate for Extract Method
A comment explaining a complex expression → candidate for Extract Variable
A method whose purpose isn't clear from its name → candidate for Rename Method
Comments describing required preconditions or invariants → candidate for Introduce Assertion
Comments that are out of date, misleading, or redundant with the code

Refactoring Treatments

1. Extract Variable

When: A comment explains a complex expression.

# Before
if (user.age >= 18 and user.country == "FR" and not user.is_banned):
    # check if user can access adult content in France
    allow_access()

# After
is_adult = user.age >= 18
is_in_france = user.country == "FR"
is_active = not user.is_banned
can_access_adult_content_in_france = is_adult and is_in_france and is_active

if can_access_adult_content_in_france:
    allow_access()

2. Extract Method

When: A comment describes what a section of code does — turn that section into a named method, using the comment text as the method name.

# Before
def process_order(order):
    # validate order items
    for item in order.items:
        if item.quantity <= 0:
            raise ValueError("Invalid quantity")
        if item.price < 0:
            raise ValueError("Invalid price")

    # calculate total
    total = sum(item.quantity * item.price for item in order.items)
    ...

# After
def process_order(order):
    validate_order_items(order.items)
    total = calculate_order_total(order.items)
    ...

def validate_order_items(items):
    for item in items:
        if item.quantity <= 0:
            raise ValueError("Invalid quantity")
        if item.price < 0:
            raise ValueError("Invalid price")

def calculate_order_total(items):
    return sum(item.quantity * item.price for item in items)

3. Rename Method

When: A method exists but its name doesn't explain what it does, so comments compensate.

# Before
def process(x):
    # converts celsius to fahrenheit
    return x * 9/5 + 32

# After
def celsius_to_fahrenheit(celsius):
    return celsius * 9/5 + 32

4. Introduce Assertion

When: A comment describes a required state or precondition for the system to work.

# Before
def set_discount(rate):
    # rate must be between 0 and 1
    self.discount = rate

# After
def set_discount(rate):
    assert 0 <= rate <= 1, "Discount rate must be between 0 and 1"
    self.discount = rate

When Comments Are Legitimate

Do NOT remove comments that:

Explain why a decision was made (business rule, workaround, regulatory requirement)

# Using SHA-1 here for legacy API compatibility — their endpoint doesn't support SHA-256

Explain a genuinely complex algorithm where simpler alternatives were exhausted
Document public API surface (docstrings for libraries, SDKs)
Reference external context (ticket numbers, spec references, legal requirements)

Step-by-Step Review Workflow

When the user shares code to review for comment smells:

Scan all comments — list each one with its type (what/why/how/outdated)
Classify each comment as:
- ✅ Legitimate (explain why, complex algorithm, API doc)
- ⚠️ Smell — explains what code does (refactor candidate)
- ❌ Outdated / misleading (delete)
For each smell, suggest the appropriate refactoring technique with a concrete example
Show before/after for the refactored snippet
Summarize payoff — how the code becomes more intuitive without the comments

Quick Reference

Comment explains...	Refactoring to apply
A complex expression	Extract Variable
What a code block does	Extract Method
What a method does	Rename Method
A required precondition	Introduce Assertion
Why a design was chosen	✅ Keep it
A complex, irreducible algo	✅ Keep it
Something outdated/wrong	❌ Delete it

comments-smells