---

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.