clean-code

---
name: clean-code
description: >
  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

## Purpose

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 to Use

- 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

- **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.

## Workflow

**A. Look something up**

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.

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

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.

## Decision Rules

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

| Topic | File | Topic | File |
|---|---|---|---|
| Boy Scout Rule, LeBlanc's law, professionalism | `references/chapters/ch01-clean-code.md` | Classes, SRP, cohesion | `references/chapters/ch10-classes.md` |
| Naming: intent-revealing, no encodings | `references/chapters/ch02-meaningful-names.md` | Systems: construction vs use, DI, factory | `references/chapters/ch11-systems.md` |
| Functions: Do One Thing, step-down, CQS, args | `references/chapters/ch03-functions.md` | Four Rules of Simple Design, emergence | `references/chapters/ch12-emergence.md` |
| Comments: good vs bad | `references/chapters/ch04-comments.md` | Concurrency: isolation, shared state | `references/chapters/ch13-concurrency.md` |
| Formatting: newspaper metaphor, ordering | `references/chapters/ch05-formatting.md` | Args case study, festering pile, refinement | `references/chapters/ch14-successive-refinement.md` |
| Objects vs data, Law of Demeter | `references/chapters/ch06-objects-and-data-structures.md` | Extract Method, Collecting Parameter | `references/chapters/ch15-junit-internals.md` |
| Errors, null, Special Case | `references/chapters/ch07-error-handling.md` | enum over int, Feature Envy fix, factory | `references/chapters/ch16-refactoring-serialdate.md` |
| Boundaries, learning tests, adapters | `references/chapters/ch08-boundaries.md` | Smells (C/E/F/G/J/N/T), DRY, ONE SWITCH | `references/chapters/ch17-smells-and-heuristics.md` |
| TDD three laws, F.I.R.S.T., BUILD-OPERATE-CHECK | `references/chapters/ch09-unit-tests.md` | | |

Cross-chapter topics: Demeter / Feature Envy -> ch06 + ch17; DRY -> ch12 + ch17;
refactoring -> ch14 + ch16; Boy Scout Rule -> ch01 + ch15.

Other routing:

- 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.

## Constraints

- **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.

## Priority

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.

## Stop Conditions

- 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.

## Verification

- [ ] 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.

## Output

- **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

Load only when needed:

- `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.

• SKILL.md 8 KB
• references/appendix-lang-map.md 6 KB
• references/cheatsheet.md 5 KB
• references/core-frameworks.md 6 KB
• references/glossary.md 5 KB
• references/patterns.md 5 KB
• references/chapters/ch01-clean-code.md 8 KB
• references/chapters/ch02-meaningful-names.md 9 KB
• references/chapters/ch03-functions.md 11 KB
• references/chapters/ch04-comments.md 9 KB
• references/chapters/ch05-formatting.md 6 KB
• references/chapters/ch06-objects-and-data-structures.md 7 KB
• references/chapters/ch07-error-handling.md 7 KB
• references/chapters/ch08-boundaries.md 5 KB
• references/chapters/ch09-unit-tests.md 5 KB
• references/chapters/ch10-classes.md 6 KB
• references/chapters/ch11-systems.md 8 KB
• references/chapters/ch12-emergence.md 6 KB
• references/chapters/ch13-concurrency.md 9 KB
• references/chapters/ch14-successive-refinement.md 10 KB
• references/chapters/ch15-junit-internals.md 9 KB
• references/chapters/ch16-refactoring-serialdate.md 8 KB
• references/chapters/ch17-smells-and-heuristics.md 13 KB