Comments (as Code Smell)

Comments used to explain bad code.

“A comment is often a deodorant. It obscures smells.” – Fowler & Beck “Don’t comment bad code—rewrite it.” – Brian Kernighan

Signs of Use (Symptoms)

  • Long block comments explaining what the next 50 lines do.
  • Comments apologizing for the code (“// Sorry for this hack”).
  • Outdated comments that contradict the code.

Why it is bad (Consequences)

  • Lies: Comments rot. Code changes, comments don’t.
  • Clutter: Noise that distracts from reading code.

Why it happens (Root Cause)

The code itself is too complex to understand, so comments are added as a bandaid.

When it might be okay (Exceptions)

  • Legal headers.
  • TODO/FIXME markers (temporary).
  • API documentation (Javadoc/TSDoc).
  • Explaining why (not what).

Explanation

Problem

A developer writes 50 lines of spaghetti, then adds a 10-line comment explaining it.

The Flaw

The energy spent on comments should be spent on making the code self-explanatory.

Real world analogy

A warning sign on a broken stair vs. fixing the stair.

Refactoring Solution

  • Rename Method / Variable: Make code self-documenting.
  • Extract Method: Name the extracted method descriptively.

Pros and Cons (of the Antipattern)

Pros (Why people do it) Cons (The price you pay)
  • Quick explanation
    		•
  • Comment rot
  • Mask for bad code
    		•

    Comparison

    • Related Antipatterns: Long Method.
    • Related Principles: KISS (Simpler code needs fewer comments).

    Code example

    Typescript

    Bad (The Antipattern)

    Good (The Fix)