Menu
Use when deciding whether, how, or where to write code comments — applies Clean Code comment principles
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when designing or reviewing exception handling, error boundaries, or error propagation patterns — applies Clean Code error handling principles
Use when designing, reviewing, or refactoring functions — applies Clean Code function principles for small, focused, well-argumented functions
Use when choosing names for variables, functions, classes, or modules — applies Clean Code naming principles for clear, intention-revealing identifiers
Routes to Clean Code sub-skills for naming, functions, comments, and error handling based on Robert C. Martin's Clean Code
Detects code smells and recommends specific refactorings. Covers the 22 canonical code smells from Fowler's Refactoring with Python examples.
Techniques for breaking down and reorganizing methods: Extract Method, Inline Method, Replace Temp with Query, Introduce Explaining Variable, Split Temporary Variable, Replace Method with Method Object, Substitute Algorithm. All with Python before/after examples.
| name | clean-code-comments |
| description | Use when deciding whether, how, or where to write code comments — applies Clean Code comment principles |
Based on Robert C. Martin's Clean Code, Chapter 4: Comments.
Trigger on:
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.
Copyright and license notices are necessary.
A short clarification that genuinely cannot be expressed in code:
# Format: ISO 8601, e.g. "2024-01-15T09:30:00Z"
timestamp = parse_timestamp(raw)
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()
Translating a confusing API or library into something readable.
# WARNING: This takes ~30s on first run due to cache warm-up
Temporary reminders for future work. Include issue/ticket reference.
Emphasizing the importance of something that might look like a mistake.
Comments that say nothing useful: // Process data
# Set the user name <-- obvious from the code
user.name = new_name
Cruft like // Constructor above every constructor. The method name says it.
// Updated 2024-01-15 by Alice -- git blame does this better.
# The name <-- zero value
name = "Alice"
Delete it. Git remembers.
A comment that documents something far away from the code it sits above.
Long historical narratives, RFC excerpts, or protocol specs in comments.
Distilled from Clean Code by Robert C. Martin, Chapter 4: Comments.