|
| 1 | +--- |
| 2 | +name: clean-code |
| 3 | +description: "Applies principles from Robert C. Martin's 'Clean Code'. Use this skill when writing, reviewing, or refactoring code to ensure high quality, readability, and maintainability. Covers naming, functio..." |
| 4 | +risk: safe |
| 5 | +source: "ClawForge (https://github.com/jackjin1997/ClawForge)" |
| 6 | +date_added: "2026-02-27" |
| 7 | +--- |
| 8 | + |
| 9 | +# Clean Code Skill |
| 10 | + |
| 11 | +This skill embodies the principles of "Clean Code" by Robert C. Martin (Uncle Bob). Use it to transform "code that works" into "code that is clean." |
| 12 | + |
| 13 | +## 🧠 Core Philosophy |
| 14 | + |
| 15 | +> "Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch |
| 16 | +
|
| 17 | +## When to Use |
| 18 | + |
| 19 | +Use this skill when: |
| 20 | + |
| 21 | +- **Writing new code**: To ensure high quality from the start. |
| 22 | +- **Reviewing Pull Requests**: To provide constructive, principle-based feedback. |
| 23 | +- **Refactoring legacy code**: To identify and remove code smells. |
| 24 | +- **Improving team standards**: To align on industry-standard best practices. |
| 25 | + |
| 26 | +## 1. Meaningful Names |
| 27 | + |
| 28 | +- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`. |
| 29 | +- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`. |
| 30 | +- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`. |
| 31 | +- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`. |
| 32 | +- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`. |
| 33 | +- **Method Names**: Use verbs (`postPayment`, `deletePage`). |
| 34 | + |
| 35 | +## 2. Functions |
| 36 | + |
| 37 | +- **Small!**: Functions should be shorter than you think. |
| 38 | +- **Do One Thing**: A function should do only one thing, and do it well. |
| 39 | +- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex). |
| 40 | +- **Descriptive Names**: `isPasswordValid` is better than `check`. |
| 41 | +- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification. |
| 42 | +- **No Side Effects**: Functions shouldn't secretly change global state. |
| 43 | + |
| 44 | +## 3. Comments |
| 45 | + |
| 46 | +- **Don't Comment Bad Code—Rewrite It**: Most comments are a sign of failure to express ourselves in code. |
| 47 | +- **Explain Yourself in Code**: |
| 48 | + ```python |
| 49 | + # Check if employee is eligible for full benefits |
| 50 | + if employee.flags & HOURLY and employee.age > 65: |
| 51 | + ``` |
| 52 | + vs |
| 53 | + ```python |
| 54 | + if employee.isEligibleForFullBenefits(): |
| 55 | + ``` |
| 56 | +- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs. |
| 57 | +- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers. |
| 58 | + |
| 59 | +## 4. Formatting |
| 60 | + |
| 61 | +- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom. |
| 62 | +- **Vertical Density**: Related lines should be close to each other. |
| 63 | +- **Distance**: Variables should be declared near their usage. |
| 64 | +- **Indentation**: Essential for structural readability. |
| 65 | + |
| 66 | +## 5. Objects and Data Structures |
| 67 | + |
| 68 | +- **Data Abstraction**: Hide the implementation behind interfaces. |
| 69 | +- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`. |
| 70 | +- **Data Transfer Objects (DTO)**: Classes with public variables and no functions. |
| 71 | + |
| 72 | +## 6. Error Handling |
| 73 | + |
| 74 | +- **Use Exceptions instead of Return Codes**: Keeps logic clean. |
| 75 | +- **Write Try-Catch-Finally First**: Defines the scope of the operation. |
| 76 | +- **Don't Return Null**: It forces the caller to check for null every time. |
| 77 | +- **Don't Pass Null**: Leads to `NullPointerException`. |
| 78 | + |
| 79 | +## 7. Unit Tests |
| 80 | + |
| 81 | +- **The Three Laws of TDD**: |
| 82 | + 1. Don't write production code until you have a failing unit test. |
| 83 | + 2. Don't write more of a unit test than is sufficient to fail. |
| 84 | + 3. Don't write more production code than is sufficient to pass the failing test. |
| 85 | +- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely. |
| 86 | + |
| 87 | +## 8. Classes |
| 88 | + |
| 89 | +- **Small!**: Classes should have a single responsibility (SRP). |
| 90 | +- **The Stepdown Rule**: We want the code to read like a top-down narrative. |
| 91 | + |
| 92 | +## 9. Smells and Heuristics |
| 93 | + |
| 94 | +- **Rigidity**: Hard to change. |
| 95 | +- **Fragility**: Breaks in many places. |
| 96 | +- **Immobility**: Hard to reuse. |
| 97 | +- **Viscosity**: Hard to do the right thing. |
| 98 | +- **Needless Complexity/Repetition**. |
| 99 | + |
| 100 | +## 🛠️ Implementation Checklist |
| 101 | + |
| 102 | +- [ ] Is this function smaller than 20 lines? |
| 103 | +- [ ] Does this function do exactly one thing? |
| 104 | +- [ ] Are all names searchable and intention-revealing? |
| 105 | +- [ ] Have I avoided comments by making the code clearer? |
| 106 | +- [ ] Am I passing too many arguments? |
| 107 | +- [ ] Is there a failing test for this change? |
0 commit comments