clean-code
Write readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "clean up this code", "this function is too long", "code smells", "naming conventions", "boy scout rule", "single responsibility", or "unit test quality". Also trigger when reviewing a pull request for readability, untangling a messy function, debating comment styles, or improving error-handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture and dependency rules, see clean-architecture.
wondelai · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add wondelai/skills --skill clean-codeAbout this skill
name: clean-code description: 'Write readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "clean up this code", "this function is too long", "code smells", "naming conventions", "boy scout rule", "single responsibility", or "unit test quality". Also trigger when reviewing a pull request for readability, untangling a messy function, debating comment styles, or improving error-handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture and dependency rules, see clean-architecture.' license: MIT metadata: author: wondelai version: "1.4.0"
Clean Code Framework
A disciplined approach to writing code that communicates intent, minimizes surprises, and welcomes change. Apply these principles when writing new code, reviewing pull requests, refactoring legacy systems, or advising on code quality.
Core Principle
Code is read far more often than it is written — optimize for the reader. The read-to-write ratio is well over 10:1, so every naming choice, function boundary, and formatting decision either adds clarity or adds cost. Clean code reads like well-written prose: names reveal intent, functions tell a story one step at a time, and the Boy Scout Rule applies — always leave the code cleaner than you found it.
Scoring
Goal: 10/10. Rate any code 0-10 against the principles below. Report the current score and the specific improvements needed to reach 10/10.
- 9-10: Names reveal intent, functions are small and focused, error handling is consistent, tests are clean and comprehensive
- 7-8: Mostly clean with minor naming ambiguities or a few long functions; tests may lack edge cases
- 5-6: Mixed — good patterns alongside unclear names, duplicated logic, or inconsistent error handling
- 3-4: Long multi-purpose functions, misleading names, poor or missing tests
- 1-2: Nearly unreadable — magic numbers, cryptic abbreviations, no structure, no tests
The Clean Code Framework
Six disciplines for writing code that communicates clearly and adapts to change:
1. Meaningful Names
Core concept: Names should reveal intent, avoid disinformation, and make the code read like prose. If a name requires a comment to explain it, the name is wrong.
Why it works: Names are the most pervasive form of documentation — a well-chosen name eliminates the need to read the implementation; a poor one forces every reader to reverse-engineer intent.
Key insights:
- A name should answer why it exists, what it does, and how it is used
- No encodings, prefixes, or type information (no Hungarian notation); single letters only for tiny-scope loop counters
- Classes are nouns; methods are verbs
- One word per concept: don't mix
fetch,retrieve, andget - Longer scope demands a longer, more descriptive name
- Rename freely — IDEs make it trivial
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Variables | Intention-revealing | elapsedTimeInDays not d |
| Booleans | Predicate phrasing | isActive, hasPermission, canEdit |
| Functions | Verb + noun | calculateMonthlyRevenue() not calc() |
| Classes | Noun naming the responsibility | InvoiceGenerator not InvoiceManager |
See references/naming-conventions.md when renaming or reviewing names — per-language conventions, pronounceable/searchable tables, and before/after examples.
2. Functions
Core concept: Functions should be small, do one thing, and do it well — ideally 4-6 lines, zero to two arguments, one level of abstraction.
Why it works: Small single-purpose functions are easy to name, understand, test, and reuse; long functions hide bugs, resist testing, and accumulate responsibilities.
Key insights:
- Step-Down Rule: code reads top-down, each function calling the next level of abstraction
- Argument count: zero best, one fine, two acceptable, three+ requires justification
- Flag arguments are a smell — the function does two things; split it
- Command-Query Separation: change state or return a value, never both
- Extract till you drop: if you can pull out a named function, do it
- No hidden side effects — the name must tell the whole truth
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Long function | Extract named steps | validateInput(); transformData(); saveRecord(); |
| Flag argument | Split into two functions | renderForPrint() / renderForScreen() not render(isPrint) |
| Error cases | Guard clauses at top | Early return for errors, single happy path |
| Many arguments | Introduce parameter object | new DateRange(start, end) not report(start, end, format, locale) |
| Side effects | Make effects explicit | checkPassword() that starts a session → rename or separate |
See references/functions-and-methods.md when splitting a long function — argument-count rules, command-query separation, and step-down worked examples.
3. Comments and Formatting
Core concept: A comment is a failure to express yourself in code. When comments are necessary, they explain why, never what. Formatting creates the visual structure that makes code scannable.
Why it works: Comments rot — code changes but comments often don't, creating documentation worse than none. Clean formatting lets developers scan code like a newspaper: headlines first, details on demand.
Key insights:
- The best comment is a well-named extracted function
- Acceptable: legal headers, TODOs, public API docs, genuine "why" explanations
- Commented-out code and journal comments: delete — version control remembers
- Vertical openness between concepts; vertical density within them; declare variables near usage
- Newspaper metaphor: high-