Clean Code

1---2name: clean-code3description: "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.\""4risk: safe5source: "ClawForge (https://github.com/jackjin1997/ClawForge)"6date_added: "2026-02-27"7---8 9# Clean Code Skill10 11This 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 Philosophy14> "Code is clean if it can be read, and enhanced by a developer other than its original author." — Grady Booch15 16## When to Use17Use this skill when:18- **Writing new code**: To ensure high quality from the start.19- **Reviewing Pull Requests**: To provide constructive, principle-based feedback.20- **Refactoring legacy code**: To identify and remove code smells.21- **Improving team standards**: To align on industry-standard best practices.22 23## 1. Meaningful Names24- **Use Intention-Revealing Names**: `elapsedTimeInDays` instead of `d`.25- **Avoid Disinformation**: Don't use `accountList` if it's actually a `Map`.26- **Make Meaningful Distinctions**: Avoid `ProductData` vs `ProductInfo`.27- **Use Pronounceable/Searchable Names**: Avoid `genymdhms`.28- **Class Names**: Use nouns (`Customer`, `WikiPage`). Avoid `Manager`, `Data`.29- **Method Names**: Use verbs (`postPayment`, `deletePage`).30 31## 2. Functions32- **Small!**: Functions should be shorter than you think.33- **Do One Thing**: A function should do only one thing, and do it well.34- **One Level of Abstraction**: Don't mix high-level business logic with low-level details (like regex).35- **Descriptive Names**: `isPasswordValid` is better than `check`.36- **Arguments**: 0 is ideal, 1-2 is okay, 3+ requires a very strong justification.37- **No Side Effects**: Functions shouldn't secretly change global state.38 39## 3. Comments40- **Don't Comment Bad Code—Rewrite It**: Most comments are a sign of failure to express ourselves in code.41- **Explain Yourself in Code**: 42  ```python43  # Check if employee is eligible for full benefits44  if employee.flags & HOURLY and employee.age > 65:45  ```46  vs47  ```python48  if employee.isEligibleForFullBenefits():49  ```50- **Good Comments**: Legal, Informative (regex intent), Clarification (external libraries), TODOs.51- **Bad Comments**: Mumbling, Redundant, Misleading, Mandated, Noise, Position Markers.52 53## 4. Formatting54- **The Newspaper Metaphor**: High-level concepts at the top, details at the bottom.55- **Vertical Density**: Related lines should be close to each other.56- **Distance**: Variables should be declared near their usage.57- **Indentation**: Essential for structural readability.58 59## 5. Objects and Data Structures60- **Data Abstraction**: Hide the implementation behind interfaces.61- **The Law of Demeter**: A module should not know about the innards of the objects it manipulates. Avoid `a.getB().getC().doSomething()`.62- **Data Transfer Objects (DTO)**: Classes with public variables and no functions.63 64## 6. Error Handling65- **Use Exceptions instead of Return Codes**: Keeps logic clean.66- **Write Try-Catch-Finally First**: Defines the scope of the operation.67- **Don't Return Null**: It forces the caller to check for null every time.68- **Don't Pass Null**: Leads to `NullPointerException`.69 70## 7. Unit Tests71- **The Three Laws of TDD**:72  1. Don't write production code until you have a failing unit test.73  2. Don't write more of a unit test than is sufficient to fail.74  3. Don't write more production code than is sufficient to pass the failing test.75- **F.I.R.S.T. Principles**: Fast, Independent, Repeatable, Self-Validating, Timely.76 77## 8. Classes78- **Small!**: Classes should have a single responsibility (SRP).79- **The Stepdown Rule**: We want the code to read like a top-down narrative.80 81## 9. Smells and Heuristics82- **Rigidity**: Hard to change.83- **Fragility**: Breaks in many places.84- **Immobility**: Hard to reuse.85- **Viscosity**: Hard to do the right thing.86- **Needless Complexity/Repetition**.87 88## 🛠️ Implementation Checklist89- [ ] Is this function smaller than 20 lines?90- [ ] Does this function do exactly one thing?91- [ ] Are all names searchable and intention-revealing?92- [ ] Have I avoided comments by making the code clearer?93- [ ] Am I passing too many arguments?94- [ ] Is there a failing test for this change?95 96## Limitations97- Use this skill only when the task clearly matches the scope described above.98- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.99- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.