Clean code comments

Skill lifeodyssey/craftsmanship-skills/skills/clean-code-comments

Agent Skills distilled from Clean Code & Refactoring. Install: npx skills add lifeodyssey/craftsmanship-skills

Install

npx -y skills add lifeodyssey/craftsmanship-skills --skill clean-code-comments

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

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

SKILL.md

2.6 KB, as published. Nobody here has run it

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

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.