clean-code · diff

git:20260825.fd539ff to git:20260925.32ce6c0

111 added, 134 removed. Audit A to A.

---

name: clean-code

description: >

- Knowledge base distilled from "Clean Code: A Handbook of Agile Software

- Craftsmanship" by Robert C. Martin (Uncle Bob). Use when applying Uncle Bob's

- frameworks for meaningful names, small functions, comments, formatting,

- objects vs data structures, error handling, boundaries, unit tests / TDD,

- class design (SRP), systems, concurrency, refactoring, and code smells;

- studying the book; or referencing its concepts during code review, cleanup,

- or TDD work.

- triggers:

- - clean code: 整洁代码/代码整洁/clean code/refactor/重构/代码质量

- - naming: 命名/meaningful names/变量名/函数名/类名/命名规范

- - functions: 函数设计/小函数/do one thing/参数/函数拆分

- - comments: 注释/comments/该不该写注释

- - tdd: TDD/单元测试/unit test/测试驱动/clean tests

- - error handling: 异常处理/error handling/异常设计

- - code smell: 代码味道/code smell/坏味道/反模式/review

- - design: SRP/面向对象/类设计/对象与数据结构/并发

+ Knowledge base distilled from "Clean Code: A Handbook of Agile Software Craftsmanship"

+ by Robert C. Martin (Uncle Bob): all 17 chapters plus a decision cheat sheet, a technique

+ and pattern catalogue, a glossary, and a cross-language map. Use it to apply Uncle Bob's

+ frameworks for meaningful names, small functions, comments, formatting, objects vs data

+ structures, error handling, boundaries, unit tests / TDD, class design (SRP), systems,

+ concurrency, refactoring, and code smells — while writing code, reviewing a diff, cleaning

+ up, or doing TDD. Trigger phrases: clean code, 整洁代码, 代码整洁, 重构, refactor, 代码质量;

+ naming, 命名, meaningful names, 变量名, 函数名, 命名规范; 函数设计, 小函数, do one thing,

+ 函数拆分; 注释, comments, 该不该写注释; TDD, 单元测试, unit test, 测试驱动, clean tests;

+ 异常处理, error handling, 异常设计; 代码味道, code smell, 坏味道, 反模式, code review;

+ SRP, 面向对象, 类设计, 对象与数据结构, 并发.

---

# Clean Code

**Author**: Robert C. Martin (Uncle Bob) | **Pages**: ~462 | **Chapters**: 17 | **Generated**: 2026-08-24

- ## How to Use This Skill

+ ## Purpose

- - **No arguments** — load core frameworks for reference (this file's Core Frameworks section).

- - **With a topic** — ask about `naming`, `functions`, `comments`, `TDD`, `error handling`, `code smells`, etc.; I find and read the relevant chapter.

- - **With a chapter** — ask for `ch03` (functions) or `ch17` (smells); I load that specific chapter file.

- - **Browse** — ask "what chapters do you have?" to see the full index.

+ A synthesised study aid for *Clean Code*: it maps every named framework, principle,

+ anti-pattern, and heuristic in the book to a reference file, then routes a question or a

+ review finding to the file that answers it. It produces grounded advice with chapter

+ citations — not the book text, and not a linting tool.

- When you ask about a topic not covered in the Core Frameworks below, I will read

- the relevant chapter file before answering, grounded in the book's actual content.

+ ## When to Use

- **Language-agnostic:** The principles in this skill are universal software-engineering

- truths, not Java rules. The book happens to use Java for its code examples, but naming,

- functions, comments, SRP, TDD, error handling, concurrency, and code smells apply to

- every language. When you name a language (e.g. "in Rust", "in Go"), I will translate

- the advice to that language using [appendix-lang-map.md](appendix-lang-map.md) instead

- of quoting Java syntax.

+ - Naming, functions, comments, formatting, objects vs data structures, error handling,

+ boundaries, tests/TDD, classes/SRP, systems, concurrency, refactoring, code smells.

+ - A live review or cleanup where you must name *why* something is a smell and what to do.

+ - Studying the book, or asking "what does Uncle Bob say about X".

+ - Trigger phrases: 整洁代码, 重构, 代码质量, 命名, 函数设计, 注释, 代码味道, 反模式, 测试驱动;

+ clean code, naming, TDD, error handling, code smell, code review, SRP.

- ---

+ ## When NOT to Use

- ## Core Frameworks & Mental Models

+ - **Review-and-fix of a diff** -> `claude-simplify` runs the review and applies fixes; this

+ skill only supplies the justification the review cites.

+ - **Beyond the book** — design patterns, architecture, framework idioms -> say it is out of

+ scope; do not extrapolate book positions.

+ - **Untrusted third-party code safety** -> `skill-security-check`.

+ - **Language tooling** (linters, formatters, rule configs) -> not covered.

- Clean Code is a discipline of *care*: code is read far more than it is written

- (reading:writing ≈ 10:1), so optimize for the reader. Below are the author's

- named, reusable frameworks — apply them, don't just recall them.

+ ## Workflow

- **Professionalism & attitude**

- - **The Boy Scout Rule** — Leave the campground cleaner than you found it. Every check-in makes one small, safe improvement (rename, extract, de-dupe). Cumulatively this prevents rot; you never need a "Grand Redesign in the Sky".

- - **LeBlanc's law** — "Later equals never." Refactoring deferred to "later" is refactoring never done. Fix it where you stand.

- - **The Primal Conundrum** — Making a mess to hit a deadline *guarantees* you miss it; the only way to go fast is to keep the code clean. Refuse requirements that force chaos (Semmelweis hand-washing analogy).

+ **A. Look something up**

- **Naming (Ch 2)**

- - **Use Intention-Revealing Names** — a name should answer why it exists, what it does, how it is used. `int daysSinceCreation` > `int d`.

- - **Avoid Disinformation / Encodings** — no `aix`/`sz` noise, no Hungarian `m_`, no type encodings (`strName`) — the language/IDE already knows types.

- - **Make Meaningful Distinctions / Pronounceable / Searchable names** — `source` vs `destination`, not `a1`/`a2`; `Customer` not `Cust`.

- - **One word per concept** — don't mix `fetch`/`get`/`retrieve` for the same idea.

+ 1. Classify the question into a topic in the Decision Rules table.

+ 2. Read **that one file**; preloading `references/` defeats the routing table.

+ 3. Follow a chapter's cross-reference only when the question actually needs it.

+ 4. Answer from the loaded content, citing chapter and heuristic ids (`Ch 3`, `G5`, `F1`).

+ 5. For a non-Java language, read `references/appendix-lang-map.md` and translate rather than

+ quoting Java syntax.

- **Functions (Ch 3)**

- - **Small! + Do One Thing** — a function does one thing, does it well, does it only. Steps inside it are one level of abstraction below its name.

- - **The Step-down Rule** — code reads top-down like a narrative; each function is followed by the next level of detail.

- - **Few arguments (≤ 3)** — niladic > monadic > dyadic > triadic; avoid output arguments (mutate the receiver, not a param); **no flag arguments** (a boolean means the function does two things — split it).

- - **Command-Query Separation** — either do something or answer something, not both.

- - **Don't repeat yourself** — duplication is a missed abstraction; DRY at function level first.

+ **B. Apply the book to a live code review**

- **Comments (Ch 4)**

- - **Comments do not make up for bad code** — express intent in code, not in commentary.

- - **Good comments only**: legal/license, informative, explanation of intent, clarification, warning of consequences, TODO (with discipline), amplification of importance, javadoc for public APIs.

- - **Bad comments**: mumbling, redundant, misleading, mandated noise, journal/change-history, position markers, commented-out code (delete it — VCS remembers).

+ 1. Read `references/cheatsheet.md` — it is the review lens.

+ 2. Tag each diff finding with its C/E/F/G/J/N/T heuristic id; load

+ `references/chapters/ch17-smells-and-heuristics.md` for tags absent from the cheat sheet.

+ 3. Name the fixing framework, then load the chapter that owns it via the routing table.

+ 4. Load `references/patterns.md` when the fix is a technique and you need its trade-offs.

+ 5. Report each finding as: id -> why -> fix -> citation.

- **Formatting (Ch 5)**

- - **The Newspaper Metaphor** — a source file reads like a newspaper: headline (name) first, high-level concepts, details downward.

- - **Vertical Distance / Ordering** — declare variables and private helpers close to where they are used; callable functions sit above the functions that call them.

+ ## Decision Rules

- **Objects vs Data Structures (Ch 6)**

- - **Data/Object Anti-Symmetry** — objects hide data and expose behavior; data structures expose data and have no meaningful behavior. Don't force one into the other.

- - **The Law of Demeter (shy code)** — a method should talk only to its friends, not friends-of-friends: avoid `a.getB().getC().doX()`. Use adapters/helpers to expose needed services.

+ Route by topic; load exactly one row's file:

- **Error Handling (Ch 7)**

- - **Use Exceptions, not return codes** — write `try-catch-finally` first; wrap third-party APIs so you control the boundary.

- - **Special Case Pattern** — return a special object (e.g. a null-safe implementation) instead of `null`.

- - **Never return null; never pass null** — both are an Open Invitation to a null-reference crash.

+ |---|---|---|---|

- **Boundaries (Ch 8)**

- - **Learning Tests** — write tests against third-party APIs you adopt to lock in behavior and detect version drift.

- - **Adapter at the boundary** — hide foreign interfaces (e.g. `Map`) behind your own small types.

+ Cross-chapter topics: Demeter / Feature Envy -> ch06 + ch17; DRY -> ch12 + ch17;

+ refactoring -> ch14 + ch16; Boy Scout Rule -> ch01 + ch15.

- **Unit Tests (Ch 9)**

- - **The Three Laws of TDD** — (1) write no production code until a failing test exists; (2) write only enough test to fail; (3) write only enough production code to pass.

- - **F.I.R.S.T.** — tests are Fast, Independent, Repeatable, Self-Validating, Timely.

- - **Tests are as clean as production** — no duplication, one concept per test; messy tests rot the suite and kill the safety net.

+ Other routing:

- **Classes (Ch 10)**

- - **Single Responsibility Principle (SRP)** — a class has one reason to change; small classes with high cohesion.

- - **Organize for change** — isolate likely-varying parts behind interfaces/factories.

+ - One-line definition only -> `references/core-frameworks.md`; escalate to the chapter after.

+ - Concrete technique or pattern + trade-offs -> `references/patterns.md`.

+ - A term you cannot place -> `references/glossary.md`, which names its chapter.

+ - A "what should I decide" question -> `references/cheatsheet.md`.

+ - Conflict between two answers -> apply Priority below.

- **Systems (Ch 11)**

- - **Separate constructing a system from using it** — `main` builds, the rest runs; use Dependency Injection / Abstract Factory so modules don't know how their collaborators are made.

+ ## Constraints

- **Emergence / Simple Design (Ch 12)**

- - **The Four Rules of Simple Design** (in priority order): (1) passes all tests; (2) contains no duplication; (3) expresses intent (small, well-named); (4) minimizes classes/methods. Test-driven emergence: keep the system running green while refining.

+ - **Never present this skill as the book's verbatim text.** It is a study aid; attribute

+ paraphrases as "the book's argument", never as a quotation.

+ - **Cite chapter and heuristic ids** whenever you assert a principle.

+ - **Do not summarise detail away.** One-liners orient only; when reasoning or edge cases

+ matter, read the chapter and answer from it.

+ - **Principles are language-agnostic.** Java examples are carriers, not the rule.

+ - **Stay in scope.** Outside *Clean Code*, say so instead of inventing book positions.

- **Concurrency (Ch 13)**

- - **SRP + Concurrency** — keep concurrent code and non-concurrent code in separate classes.

- - **Limit the scope of data / Use copies / Threads move data** — share as little mutable state as possible; confine data to single threads or use immutable copies.

+ ## Priority

- **Smells & Heuristics (Ch 17)**

- - **DRY [G5]**, **ONE SWITCH rule [G23]** (at most one switch per type, producing polymorphic objects), **Feature Envy [G14]** (a method reaches into another object's data — move it), **Magic Numbers [G25]**, **Selector Arguments [G15]**. Use the C/E/F/G/J/N/T taxonomy as a review checklist.

+ When rules compete:

- ---

+ 1. **Pass all tests** before any other design improvement — Simple Design rule 1 (Ch 12).

+ 2. Then, in the book's order: remove duplication, polish expressiveness, minimise the number

+ of classes/methods (Ch 12).

+ 3. **Project conventions and language idioms** override the Java-specific J-series heuristics.

+ 4. **Name the smell before proposing the fix** — an unnamed finding cannot be checked.

- ## Chapter Index

+ ## Stop Conditions

- | # | Title | Key Frameworks |

- |---|-------|----------------|

- | [ch01](chapters/ch01-clean-code.md) | Clean Code | Boy Scout Rule, LeBlanc's law, code-sense |

- | [ch02](chapters/ch02-meaningful-names.md) | Meaningful Names | Intention-Revealing, Avoid Encoding, One Word/Concept |

- | [ch03](chapters/ch03-functions.md) | Functions | Small/Do One Thing, Step-down Rule, CQS, ≤3 args |

- | [ch04](chapters/ch04-comments.md) | Comments | Comments ≠ bad code, Good vs Bad comments |

- | [ch05](chapters/ch05-formatting.md) | Formatting | Newspaper Metaphor, Vertical Distance/Ordering |

- | [ch06](chapters/ch06-objects-and-data-structures.md) | Objects and Data Structures | Data/Object Anti-Symmetry, Law of Demeter |

- | [ch07](chapters/ch07-error-handling.md) | Error Handling | Exceptions > return codes, Special Case, no null |

- | [ch08](chapters/ch08-boundaries.md) | Boundaries | Learning Tests, Adapter Pattern |

- | [ch09](chapters/ch09-unit-tests.md) | Unit Tests | Three Laws of TDD, F.I.R.S.T., BUILD-OPERATE-CHECK |

- | [ch10](chapters/ch10-classes.md) | Classes | SRP, Cohesion, Organize for Change |

- | [ch11](chapters/ch11-systems.md) | Systems | Separate Construct/Use, DI, Abstract Factory |

- | [ch12](chapters/ch12-emergence.md) | Emergence | Four Rules of Simple Design, TCR |

- | [ch13](chapters/ch13-concurrency.md) | Concurrency | SRP+Concurrency, Limit Scope of Data, Copies |

- | [ch14](chapters/ch14-successive-refinement.md) | Successive Refinement | Args case study, incremental refactoring |

- | [ch15](chapters/ch15-junit-internals.md) | JUnit Internals | Boy Scout Rule, Extract Method, Collecting Parameter |

- | [ch16](chapters/ch16-refactoring-serialdate.md) | Refactoring SerialDate | enum over int, Abstract Factory, Feature Envy fix |

- | [ch17](chapters/ch17-smells-and-heuristics.md) | Smells and Heuristics | C/E/F/G/J/N/T taxonomy, DRY, ONE SWITCH |

+ - Stop once the routed file answers the question; never read all 17 chapters.

+ - Do not chase a framework past the one linked chapter unless the user wants the derivation.

+ - Topic outside the book -> stop and say so.

- ## Topic Index

+ ## Verification

- - **Naming** → ch02

- - **Functions / Do One Thing / CQS** → ch03

- - **Comments** → ch04

- - **Formatting** → ch05

- - **Objects / Data Structures / Demeter** → ch06, ch17

- - **Error Handling / Exceptions / null** → ch07

- - **Boundaries / Learning Tests** → ch08

- - **TDD / Unit Tests / F.I.R.S.T.** → ch09

- - **Classes / SRP / Cohesion** → ch10

- - **Systems / DI / Factory** → ch11

- - **Simple Design** → ch12

- - **Concurrency** → ch13

- - **Refactoring** → ch14, ch16

- - **Code Smells / Heuristics** → ch17

- - **Boy Scout Rule** → ch01, ch15

- - **DRY** → ch12, ch17

- - **Cross-language (TS/Python/C++/Go/Rust)** → appendix-lang-map

+ - [ ] The answer cites at least one chapter or heuristic id.

+ - [ ] Only the routed file(s) were loaded, not the whole `references/` directory.

+ - [ ] Non-Java requests were translated via `references/appendix-lang-map.md`.

+ - [ ] Nothing is presented as a verbatim book quotation.

+ - [ ] Review findings are reported as id -> why -> fix -> citation.

- ## Supporting Files

+ ## Output

- - [glossary.md](glossary.md) — key terms with definitions and chapter references

- - [patterns.md](patterns.md) — techniques and design patterns from the book

- - [cheatsheet.md](cheatsheet.md) — decision rules, trade-off matrices, and smell quick-reference

- - [appendix-lang-map.md](appendix-lang-map.md) — how to apply the principles in any language (TS/Python/C++/Go/Rust) and which heuristics are Java-specific

+ - **Outcome**: Clean Code guidance with chapter citations, or a coded review of a diff.

+ - **Done when**: the question is classified, the routed reference was read, and the answer

+ cites its source.

+ - **Evidence**: the framework or smell id, its chapter, and the concrete change to make.

- ---

+ ## References

- ## Scope & Limits

+ Load only when needed:

- This skill covers the content of *Clean Code* only. It is a synthesized study

- aid (frameworks, principles, anti-patterns, worked examples), not the book text.

- For hands-on implementation in your own codebase, combine it with project-specific

- tools and your language's conventions. For topics beyond this book (e.g. broader

- design patterns, architecture, or language-specific idioms), consult related

- skills or ask the agent directly.

+ - `references/core-frameworks.md` — read for a one-line definition before escalating.

+ - `references/cheatsheet.md` — read first for any live review or "what should I decide" case.

+ - `references/glossary.md` — read when a term is unfamiliar; it gives the owning chapter.

+ - `references/patterns.md` — read when the fix needs a technique and its trade-offs.

+ - `references/appendix-lang-map.md` — read before quoting Java syntax to a non-Java user.

+ - `references/chapters/` — read only the single chapter named by the routing table.

+ ## Related Skills

+ - `claude-simplify` — runs a diff review and fixes findings; pair with this skill for the

+ taxonomy behind each finding.

+ - `skill-security-check` — pre-install safety review, a different concern.