Clean Code vs. Clear Code: Why Comments Were Never the Real Problem

The Dogma: 'Comments Are a Code Smell'

In many programming circles, developers repeat the famous mantra:

"Good code is self-documenting. If you need a comment, your code is bad."

This dogma has led thousands of developers to delete helpful context, leaving behind cryptic code that requires 30 minutes of git-blaming to understand why a specific edge case was handled.

Comments were never the enemy. Redundant comments that explain WHAT instead of WHY are the problem.

The Difference Between Clean Code and Clear Code:

1. What Clean Code Does:

• Short, single-responsibility functions.
• Expressive, domain-accurate naming.
• Low cyclomatic complexity.
• SOLID principles and decoupled layers.

2. What Clear Code Does:

• Communicates intent, trade-offs, and domain constraints.
• Answers: "Why did we choose this algorithm over that one?"
• Documents external system quirks: "We must delay 50ms here because Safari iOS 16 has a viewport resize bug."

When to Write Comments:

• Explain WHY, not WHAT:

  // BAD: Increment counter by 1
  count++;

  // GOOD: Stripe requires timestamps rounded to the nearest minute to prevent duplicate webhook delivery
  const timestamp = Math.floor(Date.now() / 60000) * 60;

• Document Edge Cases & Bug Fixes: Link to issue tracker numbers.
• Explain Non-Obvious Performance Optimizations: Why a bitwise operation was used instead of a standard loop.