Loading
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", "n
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add wondelai/skills --skill clean-code -a cursor -y
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.
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.
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.
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.
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.
Six disciplines for writing code that communicates clearly and adapts to change:
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:
fetch, retrieve, and getCode 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.
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:
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.
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:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Explaining "what" | Replace with better name | // check if eligible → isEligible() |
| Explaining "why" | Keep as comment | // RFC 7231 requires this header for proxies |
| Commented-out code | Delete it | Trust version control |
| Team formatting | Decide once, automate | Prettier, Black, gofmt |
See references/comments-formatting.md when deciding whether a comment earns its place — good-vs-bad comment catalog and vertical-formatting rules.
Core concept: Error handling is a separate concern from business logic. Use exceptions rather than return codes, provide context with every exception, and never return or pass null.
Why it works: Return codes clutter the happy path with checks; exceptions separate the two cleanly. Returning null forces null checks on every caller, and one missing check crashes far from the source.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Null returns | Empty collection or Optional | return Collections.emptyList() not return null |
| Error codes | Replace with exceptions | throw new InsufficientFundsException(balance, amount) |
| Third-party APIs | Wrap with adapter | PortfolioService wraps the vendor API, translates its exceptions |
| Special cases | Null Object pattern | GuestUser with default behavior instead of null checks |
| Context in errors | Include operation + state | "Failed to save invoice #1234 for customer 'Acme'" |
See references/error-handling.md when designing exception or null strategy — Special Case pattern and third-party-API wrapping examples.
Core concept: Tests are first-class code, kept clean with the same discipline as production code. Dirty tests are worse than no tests — they become a liability that slows every change.
Why it works: Clean tests are executable documentation and a safety net for refactoring; dirty tests make every modification a fight through incomprehensible test code.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Test structure | Arrange-Act-Assert | Setup, execute, verify — clearly separated |
| Test naming | Scenario + expected behavior | shouldRejectExpiredToken not test1 |
| Shared setup | Builder/factory helpers | aUser().withRole(ADMIN).build() |
| Flaky tests | Remove external dependencies | Mock time, network, file system |
See references/testing-principles.md when writing or cleaning tests — TDD laws, F.I.R.S.T. expanded, and clean-test patterns.
Core concept: Smells are surface indicators of deeper design problems — learn to recognize them quickly and apply targeted refactorings instead of vague "cleanup".
Why it works: Smells are heuristics that point toward likely problems without deep analysis, turning code review instinct into specific, repeatable moves.
Key insights:
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Duplication | Extract shared logic | Common validation → validateEmail() helper |
| Feature envy | Move method to the data's class | order.calculateTotal() not calculator.total(order) |
| Dead code | Delete it | Remove unused functions, unreachable branches |
| Magic numbers | Named constants | MAX_LOGIN_ATTEMPTS = 5 not bare 5 |
| Shotgun surgery | Consolidate related changes | Group scattered logic into a single module |
See references/code-smells.md when a smell is hard to name — the full catalog by category, each paired with its targeted refactoring.
| Mistake | Why It Fails | Fix |
|---|---|---|
| Abbreviating names | Saves seconds writing, costs hours reading | Full descriptive names; IDEs autocomplete |
| "Clever" one-liners | Impressive to write, impossible to debug | Expand into readable named steps |
| Comments instead of refactoring | Comments rot; code is the truth | Extract a well-named function instead |
| Catching generic exceptions | Swallows bugs along with expected errors | Catch specific exceptions; let the rest propagate |
| No tests for error paths | Happy path works, edge cases crash | Test every branch, boundary, and failure mode |
| Premature optimization | Obscures intent for marginal gains | Clean first; optimize measured bottlenecks |
| God classes | One 2000-line class does everything | Apply SRP — split by responsibility |
| Refactoring without tests | No safety net for regressions | Write characterization tests first |
| Inconsistent conventions | Every file feels like a different codebase | Agree on style; enforce with linters and formatters |
| Returning null everywhere | Null checks spread like a virus | Optional, empty collections, or Null Object |
| Question | If No | Action |
|---|---|---|
| Can you understand each function without reading its body? | Names don't reveal intent | Rename to describe what it does |
| Are all functions under 20 lines? | Functions do too many things | Extract sub-operations into named helpers |
| Zero commented-out code blocks? | Dead code creating confusion | Delete — version control has history |
| Is error handling separate from business logic? | Try-catch clutters the main flow | Extract handlers; exceptions over return codes |
| Does every class have a single responsibility? | Classes accumulate unrelated duties | Split into focused, well-named classes |
| Is there a test for every public method? | No safety net for changes | Add tests before changing further |
| Are test names descriptive of behavior? | Failures are hard to interpret | Rename to shouldDoXWhenY |
| Is duplication below 3 occurrences? | Copy-paste spreading bugs | Extract shared logic (§6) |
| Are magic numbers named constants? | Intent hidden behind raw values | Name the constant (§6) |
| Do all tests run in under 10 seconds? | Slow tests don't get run | Mock external deps; split integration tests |
Based on Robert C. Martin's seminal guide to software craftsmanship:
Robert C. Martin ("Uncle Bob") has been programming since 1970, co-authored the Agile Manifesto, and founded Uncle Bob Consulting and Clean Coders. His books — Clean Code, The Clean Coder, Clean Architecture, and Clean Agile — shaped how a generation of developers think about code quality, and his core stance is that the only way to go fast is to go well.