Clean code

--- name: clean-code description: 'Write readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "code review," "naming conventions," "function too long," "code smells," "readable code," "Boy Scout rule," "single responsibility," or "unit test quality." Also trigger when reviewing pull requests for readability, refactoring messy functions, debating comment styles, or improving error handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture, see clean-architecture.' license: MIT metadata: author: wondelai version: "1.2.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 on a scale of 0:10 based on 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, and 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 misleading information, 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 the 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 loop counters with a very narrow scope - Classes are nouns; methods are verbs - One word per concept: don’t mix “fetch,” “retrieve,” and “get” - A longer scope requires a longer, more descriptive name - Rename freely:IDEs make it trivial Code examples: | 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 ### 2. Functions Core concept: Functions should be small, do one thing, and do it well:ideally 4:6 lines, zero to two arguments, and one level of abstraction. Why it works: Small, single-purpose functions are easy to name, understand, test, and reuse; long functions hide bugs, make testing difficult, and accumulate responsibilities. Key insights: - Step-Down Rule: code is read top-down, with each function calling the next level of abstraction - Argument count: zero is best, one is fine, two is acceptable, three or more requires justification - Flag arguments are a code 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 extract a named function, do it - No hidden