asepharyana
0aebde93ea
- Add MANDATORY prefix to clean-code and clean-architecture descriptions - Change 'core skills' to 'mandatory' in detect-project.sh output - Both skills now always active, not just context-triggered
99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
---
|
|
name: clean-code
|
|
description: MANDATORY — always active. Clean Code principles: naming, functions, comments, formatting, error handling, classes. Apply to every session regardless of context. Use whenever the user writes code, reviews code, refactors, or mentions clean-code concepts in any language. Also engage proactively from code quality signals — poor naming, long functions, deep nesting, unclear abstractions. Works regardless of spoken language.
|
|
---
|
|
|
|
# Clean Code
|
|
|
|
Core principles for writing readable, maintainable, and professional code.
|
|
|
|
## Philosophy
|
|
|
|
1. **Code is read far more than written** — ratio >10:1. Optimize for the reader.
|
|
2. **Boy Scout Rule** — leave every module cleaner than you found it.
|
|
3. **The only way to go fast is to go well.** Dirty code slows everyone down.
|
|
|
|
## 1. Meaningful Names
|
|
|
|
- Use **intention-revealing names** — what is it, why does it exist, how is it used?
|
|
- **Avoid disinformation** — don't call it `accountList` unless it's a `List`. No `l`/`O` as variable names.
|
|
- **Pronounceable, searchable names** — `genymdhms` is not acceptable.
|
|
- **Class names** are nouns (`Customer`), **method names** are verbs (`postPayment`).
|
|
- **One word per concept** — standardize `fetch` vs `retrieve` vs `get`.
|
|
- **Ubiquitous language** — use the business domain's vocabulary consistently.
|
|
|
|
## 2. Functions
|
|
|
|
- **Small.** Target ~20 lines. If you can't see the whole function, it's too long.
|
|
- **Do one thing.** Operational test: you cannot extract another function from it.
|
|
- **One level of abstraction per function** — the Step-Down Rule.
|
|
- **Few arguments.** 0 ideal, 1-2 fine, 3 suspect, 4+ → need a struct or a split.
|
|
- **No flag arguments.** `render(true)` → split into `renderForSuite()` and `renderForSingleTest()`.
|
|
- **No side effects.** A function named `checkPassword` must not also log a session.
|
|
- **Command-Query Separation** — either *do* or *answer*, never both.
|
|
- **Prefer exceptions (or Result types) to error codes.**
|
|
- **DRY** — Don't Repeat Yourself. Duplication is the #1 smell.
|
|
|
|
## 3. Comments
|
|
|
|
> "Don't comment bad code — rewrite it." — Brian Kernighan
|
|
|
|
Every comment is a failure to make code self-explanatory. Before writing a comment, ask: *can I rename or extract?*
|
|
|
|
**Good comments (rare):**
|
|
- Legal headers, regex explanations, wire protocol details
|
|
- **Intent** — *why* (not *what*)
|
|
- Warnings of consequences ("this test takes two hours")
|
|
- TODOs (prune regularly)
|
|
|
|
**Delete on sight:** redundant comments, journaling (`// added by Rick`), closing-brace comments, commented-out code, mandated noise.
|
|
|
|
## 4. Formatting
|
|
|
|
- **Newspaper metaphor:** high-level first, details as you scroll.
|
|
- **Vertical density:** related concepts close together. Caller above callee.
|
|
- **Blank lines** separate concepts, not pad.
|
|
- **Indentation = abstraction signal.** Ideal functions have ≤2 indentation levels.
|
|
|
|
## 5. Objects and Data Structures
|
|
|
|
- **DTOs are data structures, not objects.**
|
|
- **Law of Demeter** — don't talk to strangers. No train wrecks (`a.getB().getC().doSomething()`).
|
|
- **Tell, don't ask** — tell the object to do the work instead of asking for state and deciding.
|
|
|
|
## 6. Error Handling
|
|
|
|
- Use exceptions/Result types, not return codes.
|
|
- Write try-catch-finally first when an operation can fail.
|
|
- Wrap third-party exceptions in your own types.
|
|
- **Don't return null.** Return empty collections or use Option/Result.
|
|
- **Don't pass null.** Fail fast at boundaries.
|
|
|
|
## 7. Tests
|
|
|
|
- **Three Laws of TDD:** 1) no production code without a failing test, 2) no more test than sufficient to fail, 3) no more production code than sufficient to pass.
|
|
- **F.I.R.S.T.:** Fast, Independent, Repeatable, Self-validating, Timely.
|
|
- Test code is first-class — same quality as production code.
|
|
|
|
## 8. Classes
|
|
|
|
- **Small by responsibility**, not by lines. SRP: one reason to change, one actor.
|
|
- **Cohesion** — methods should use most instance variables. Low cohesion = two classes in one.
|
|
- **Organize for change** — isolate volatile concepts behind interfaces.
|
|
|
|
## 9. Systems
|
|
|
|
- **Separate construction from use** — wiring lives in one place.
|
|
- **Dependency injection** over hardcoded `new` deep in business logic.
|
|
- Cross-cutting concerns (logging, security, metrics) belong in middleware, not scattered code.
|
|
|
|
## Code Smells — Quick Checklist
|
|
|
|
| Category | Smells |
|
|
|----------|--------|
|
|
| Functions | >3 args, flag params, dead params, obscure intent, misplaced responsibility |
|
|
| Classes | Feature envy, god class, inappropriate intimacy, lazy class |
|
|
| General | Duplication, magic numbers, inconsistent naming, negative conditionals, switch on type |
|
|
| Names | `data`/`info`/`handle`, not matching abstraction level, Hungarian notation |
|
|
| Tests | Insufficient coverage, skipped tests, order-dependent, slow, over-mocking |
|