clean-code-comments

name	clean-code-comments
description	Use when deciding whether, how, or where to write code comments — applies Clean Code comment principles

Clean Code: Comments

Based on Robert C. Martin's Clean Code, Chapter 4: Comments.

When to Use This Skill

Trigger on:

• Code review flagging missing or excessive comments
• "Should I add a comment here?" questions
• Debates about documentation style
• Reviewing comment quality in a PR

Core Principle

Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.

Good Comments (When to Keep/Write)

1. Legal Comments

Copyright and license notices are necessary.

2. Informative Comments

A short clarification that genuinely cannot be expressed in code:

# Format: ISO 8601, e.g. "2024-01-15T09:30:00Z"
timestamp = parse_timestamp(raw)

3. Explanation of Intent

Why a decision was made, not what the code does:

# Retry up to 3 times because the upstream service
# occasionally returns 503 during deployment windows
for attempt in range(3):
    result = call_service()

4. Clarification

Translating a confusing API or library into something readable.

5. Warning of Consequences

# WARNING: This takes ~30s on first run due to cache warm-up

6. TODO Comments

Temporary reminders for future work. Include issue/ticket reference.

7. Amplification

Emphasizing the importance of something that might look like a mistake.

Bad Comments (Remove These)

1. Mumbling

Comments that say nothing useful: // Process data

2. Redundant Comments

# Set the user name       <-- obvious from the code
user.name = new_name

3. Mandated Comments

Cruft like // Constructor above every constructor. The method name says it.

4. Journal Comments

// Updated 2024-01-15 by Alice -- git blame does this better.

5. Noise Comments

# The name              <-- zero value
name = "Alice"

6. Commented-Out Code

Delete it. Git remembers.

7. Non-local Information

A comment that documents something far away from the code it sits above.

8. Too Much Information

Long historical narratives, RFC excerpts, or protocol specs in comments.

Quick Checklist

• Does the comment say something the code cannot?
• If I rename the function, does the comment become redundant?
• Is this comment about WHY, not WHAT?
• Would better naming eliminate this comment?
• Is it a TODO with a reference to a ticket?

Source

Distilled from Clean Code by Robert C. Martin, Chapter 4: Comments.