clean-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean Code Framework

整洁代码框架

A disciplined approach to writing code that communicates intent, minimizes surprises, and welcomes change. Apply these principles when writing new code, reviewing pull requests, refactoring legacy systems, or advising on code quality improvements.

一种系统化的代码编写方法，能够清晰传达代码意图、减少意外情况并便于后续修改。在编写新代码、审查合并请求、重构遗留系统或提供代码质量改进建议时，均可应用这些原则。

Core Principle

核心原则

Code is read far more often than it is written. Optimize for the reader. Every naming choice, function boundary, and formatting decision either adds clarity or adds cost. The ratio of time spent reading code to writing code is well over 10:1. Making code easier to read makes it easier to write, easier to debug, and easier to extend.

The foundation: Clean code is not about following rules mechanically -- it is about caring for the craft. A clean codebase reads like well-written prose: names reveal intent, functions tell a story one step at a time, and there are no surprises lurking in dark corners. The Boy Scout Rule applies: always leave the code cleaner than you found it.

代码的阅读次数远多于编写次数。请为阅读者优化代码。 每一个命名选择、函数边界和格式决策，要么提升代码清晰度，要么增加维护成本。代码阅读与编写的时间比远超10:1。让代码更易读，会让编写、调试和扩展代码的过程也更轻松。

基础理念： 整洁代码并非机械地遵循规则——而是对代码技艺的重视。整洁的代码库读起来像一篇文笔流畅的散文：命名清晰传达意图，函数一步步讲述逻辑，没有隐藏在角落的意外情况。童子军规则（Boy Scout Rule）同样适用：始终让代码比你接手时更整洁。

Scoring

评分标准

Goal: 10/10. When reviewing or writing code, rate it 0-10 based on adherence to the principles below. A 10/10 means full alignment with all guidelines; lower scores indicate gaps to address. Always provide the current score and specific improvements needed to reach 10/10.

9-10: Names reveal intent, functions are small and focused, error handling is consistent, tests are clean and comprehensive.
7-8: Mostly clean with minor naming ambiguities or a few long functions. Tests exist but may lack edge cases.
5-6: Mixed quality -- some good patterns alongside unclear names, duplicated logic, or inconsistent error handling.
3-4: Significant readability issues -- long functions doing multiple things, misleading names, poor or missing tests.
1-2: Code works but is nearly unreadable -- magic numbers, cryptic abbreviations, no structure, no tests.

目标：10/10。 在审查或编写代码时，根据以下原则的符合程度为代码评分（0-10分）。10/10表示完全符合所有准则；分数越低，说明存在越多需要改进的地方。评分时需给出当前分数以及具体的改进方向。

9-10分： 命名清晰传达意图，函数短小且聚焦，错误处理一致，测试清晰全面。
7-8分： 整体整洁，但存在少量命名模糊或过长函数的问题。测试存在，但可能缺少边缘场景覆盖。
5-6分： 质量参差不齐——既有良好的代码模式，也存在命名模糊、逻辑重复或错误处理不一致的问题。
3-4分： 可读性问题严重——函数过长且职责混杂，命名具有误导性，测试缺失或质量差。
1-2分： 代码能运行但几乎无法阅读——存在魔数、晦涩缩写、无结构、无测试。

The Clean Code Framework

整洁代码框架

Six disciplines for writing code that communicates clearly and adapts to change:

编写清晰易懂、易于修改的代码需遵循六大规范：

1. Meaningful Names

1. 有意义的命名

Core concept: Names should reveal intent, avoid disinformation, and make the code read like prose. If a name requires a comment to explain it, the name is wrong.

Why it works: Names are the most pervasive form of documentation. A well-chosen name eliminates the need to read the implementation. A poorly chosen name forces every reader to reverse-engineer the author's intent.

Key insights:

Names should answer why it exists, what it does, and how it is used
Avoid single-letter variables except for loop counters in tiny scopes
Avoid encodings, prefixes, and type information in names (no Hungarian notation)
Class names should be nouns or noun phrases; method names should be verbs or verb phrases
Use one word per concept consistently: don't mix
```
fetch
```
,
```
retrieve
```
, and
```
get
```
Longer scopes demand longer, more descriptive names
Don't be afraid to rename -- IDEs make it trivial

Code applications:

Context	Pattern	Example
Variables	Intention-revealing name	`elapsedTimeInDays` not `d` or `elapsed`
Booleans	Predicate phrasing	`isActive` , `hasPermission` , `canEdit`
Functions	Verb + noun describing action	`calculateMonthlyRevenue()` not `calc()`
Classes	Noun describing responsibility	`InvoiceGenerator` not `InvoiceManager`
Constants	Searchable, all-caps with context	`MAX_RETRY_ATTEMPTS = 3` not `3` inline
Collections	Plural nouns or descriptive phrases	`activeUsers` not `list` or `data`

See: references/naming-conventions.md

核心概念： 命名应清晰传达意图，避免误导，让代码读起来像自然语言。如果一个名称需要注释来解释，那这个名称就是不合格的。

作用： 命名是最普遍的文档形式。一个恰当的名称能让阅读者无需查看实现细节。一个糟糕的名称会迫使每个阅读者反向推导作者的意图。

关键要点：

命名应回答「为什么存在」「做什么」「如何使用」的问题
除了极小作用域内的循环计数器，避免使用单字母变量
避免在命名中加入编码、前缀或类型信息（不要使用匈牙利命名法）
类名应为名词或名词短语；方法名应为动词或动词短语
同一概念使用统一词汇：不要混用
```
fetch
```
、
```
retrieve
```
和
```
get
```
作用域越大，命名应越长、越具描述性
不要害怕重命名——IDE让这个操作变得极其简单

代码应用示例：

场景	模式	示例
变量	传达意图的名称	`elapsedTimeInDays` 而非 `d` 或 `elapsed`
布尔值	谓词表述	`isActive` , `hasPermission` , `canEdit`
函数	动词+名词描述动作	`calculateMonthlyRevenue()` 而非 `calc()`
类	描述职责的名词	`InvoiceGenerator` 而非 `InvoiceManager`
常量	可搜索、全大写并带上下文	`MAX_RETRY_ATTEMPTS = 3` 而非内联的 `3`
集合	复数名词或描述性短语	`activeUsers` 而非 `list` 或 `data`

参考：references/naming-conventions.md

2. Functions

2. 函数

Core concept: Functions should be small, do one thing, and do it well. The ideal function is 4-6 lines long, takes zero to two arguments, and operates at a single level of abstraction.

Why it works: Small functions are easy to name, easy to understand, easy to test, and easy to reuse. When a function does one thing, its name can describe exactly what it does, eliminating the need to read the body. Long functions hide bugs, resist testing, and accumulate responsibilities over time.

Key insights:

Functions should do one thing, do it well, and do it only
The Step-Down Rule: code should read like a top-down narrative, each function calling the next level of abstraction
Ideal argument count is zero (niladic), then one (monadic), then two (dyadic); three or more (polyadic) requires justification
Flag arguments (booleans) are a code smell -- they mean the function does two things
Command-Query Separation: a function should either change state or return a value, never both
Extract till you drop: if you can extract a named function from a block, do it
Functions should have no side effects -- no hidden changes to state

Code applications:

Context	Pattern	Example
Long function	Extract into named steps	`validateInput(); transformData(); saveRecord();`
Flag argument	Split into two functions	`renderForPrint()` and `renderForScreen()` not `render(isPrint)`
Deep nesting	Extract inner blocks	Move nested `if` / `for` bodies into named functions
Multiple returns	Guard clauses at top	Early return for error cases, single happy path
Many arguments	Introduce parameter object	`new DateRange(start, end)` not `report(start, end, format, locale)`
Side effects	Make effects explicit	Rename `checkPassword()` to `checkPasswordAndInitSession()` or separate

See: references/functions-and-methods.md

核心概念： 函数应短小、单一职责且表现出色。理想的函数长度为4-6行，接受0-2个参数，且仅处理单一抽象层级的逻辑。

作用： 短小的函数易于命名、理解、测试和复用。当函数只做一件事时，其名称就能准确描述功能，无需阅读函数体。过长的函数会隐藏bug，难以测试，且会随着时间推移积累过多职责。

关键要点：

函数应只做一件事，做好这件事，且只做这件事
自上而下规则：代码应像自上而下的叙事，每个函数调用下一层级的抽象逻辑
理想参数数量为0（无参），其次是1（单参），然后是2（双参）；3个及以上参数（多参）需要合理的理由
标志参数（布尔值）是代码异味——这意味着函数在做两件事
命令查询分离：函数要么修改状态，要么返回值，不可两者兼具
持续提取：如果能从代码块中提取出一个命名清晰的函数，就去做
函数不应有副作用——不要隐藏状态修改

代码应用示例：

场景	模式	示例
长函数	提取为命名步骤	`validateInput(); transformData(); saveRecord();`
标志参数	拆分为两个函数	`renderForPrint()` 和 `renderForScreen()` 而非 `render(isPrint)`
深层嵌套	提取内部代码块	将嵌套的 `if` / `for` 体提取为命名函数
多返回值	顶部使用守卫语句	错误场景提前返回，主流程单一清晰
多参数	引入参数对象	`new DateRange(start, end)` 而非 `report(start, end, format, locale)`
副作用	让副作用显式化	将 `checkPassword()` 重命名为 `checkPasswordAndInitSession()` ，或拆分为两个函数

参考：references/functions-and-methods.md

3. Comments and Formatting

3. 注释与格式

Core concept: A comment is a failure to express yourself in code. Good code is self-documenting. When comments are necessary, they should explain why, never what. Formatting creates the visual structure that makes code scannable.

Why it works: Comments rot. Code changes but comments often do not, creating misleading documentation that is worse than no documentation. Clean formatting -- consistent indentation, vertical spacing between concepts, and logical ordering -- lets developers scan code the way readers scan a newspaper: headlines first, details on demand.

Key insights:

The best comment is the code itself -- extract a well-named function instead of writing a comment
Legal comments (copyright headers) and TODO comments are acceptable
Javadoc for public APIs is valuable; Javadoc for internal code is noise
Commented-out code should be deleted -- version control remembers it
Journal comments (changelog in the file) are obsolete -- use git log
Vertical openness: separate concepts with blank lines
Vertical density: related code should appear close together
Variables should be declared close to their usage
Instance variables should be declared at the top of the class

Code applications:

Context	Pattern	Example
Explaining "what"	Replace with better name	Rename `// check if eligible` to `isEligible()`
Explaining "why"	Keep as comment	`// RFC 7231 requires this header for proxies`
Commented-out code	Delete it	Trust version control to remember
File organization	Newspaper metaphor	High-level functions at top, details below
Related code	Group vertically	Keep caller near callee in the same file
Team formatting	Agree on rules once	Use automated formatters (Prettier, Black, gofmt)

See: references/comments-formatting.md

核心概念： 注释是代码无法自我表达的失败。优秀的代码是自文档化的。当必须使用注释时，应解释「为什么」，而非「是什么」。代码格式构建的视觉结构能让代码更易于扫描。

作用： 注释会过时。代码会更新，但注释往往不会，这会产生误导性的文档，比没有文档更糟糕。整洁的格式——一致的缩进、概念间的垂直间距、逻辑化的排序——让开发者能像读者读报纸一样扫描代码：先看标题，再按需查看细节。

关键要点：

最好的注释就是代码本身——提取一个命名清晰的函数，而非编写注释
法律注释（版权头）和TODO注释是可接受的
公共API的Javadoc有价值；内部代码的Javadoc是冗余信息
被注释掉的代码应删除——版本控制系统会记录它
日志注释（文件内的变更日志）已过时——使用git log
垂直留白：用空行分隔不同概念
垂直密度：相关代码应放在一起
变量应在靠近使用的位置声明
实例变量应在类的顶部声明

代码应用示例：

场景	模式	示例
解释「是什么」	替换为更好的名称	将 `// check if eligible` 重命名为 `isEligible()`
解释「为什么」	保留为注释	`// RFC 7231要求代理必须包含此头部`
被注释的代码	删除它	相信版本控制系统会记录历史
文件组织	报纸隐喻	高级函数在顶部，细节在下方
相关代码	垂直分组	在同一文件中让调用方靠近被调用方
团队格式规范	一次性达成共识	使用自动化格式化工具（Prettier、Black、gofmt）

参考：references/comments-formatting.md

4. Error Handling

4. 错误处理

Core concept: Error handling is a separate concern from business logic. Use exceptions rather than return codes, provide context with every exception, and never return or pass null.

Why it works: Return codes force the caller to check immediately, cluttering the happy path with error-checking logic. Exceptions let you separate the happy path from error handling, making both easier to read. Returning null forces every caller to add null checks, and a single missing check produces a NullPointerException far from the source.

Key insights:

Write your try-catch block first -- it defines a transaction boundary
Use unchecked exceptions -- checked exceptions violate the Open/Closed Principle
Create informative exception messages: include the operation that failed and the context
Define exception classes in terms of the caller's needs, not the type of failure
The Special Case Pattern: return a special-case object instead of null (e.g., empty list, guest user)
Don't return null -- return empty collections, Optional, or throw
Don't pass null -- no reasonable behavior exists for null arguments
Wrap third-party APIs to translate their exceptions into your domain

Code applications:

Context	Pattern	Example
Null returns	Return empty collection or Optional	`return Collections.emptyList()` not `return null`
Error codes	Replace with exceptions	`throw new InsufficientFundsException(balance, amount)`
Third-party APIs	Wrap with adapter	`PortfolioService` wraps vendor API, translates exceptions
Null arguments	Fail fast with assertion	`Objects.requireNonNull(user, "user must not be null")`
Special cases	Null Object pattern	`GuestUser` with default behavior instead of null checks
Context in errors	Include operation + state	`"Failed to save invoice #1234 for customer 'Acme'"`

See: references/error-handling.md

核心概念： 错误处理是与业务逻辑分离的独立关注点。使用异常而非返回码，为每个异常提供上下文，绝不返回或传递null。

作用： 返回码会迫使调用方立即检查，让主流程被错误检查逻辑打乱。异常能让你将主流程与错误处理分离，让两者都更易读。返回null会迫使每个调用方添加null检查，而任何一处遗漏的检查都会在远离问题源头的地方产生NullPointerException。

关键要点：

先编写try-catch块——它定义了事务边界
使用非受检异常——受检异常违反开闭原则
创建信息丰富的异常消息：包含失败的操作和上下文
根据调用方的需求定义异常类，而非根据失败类型
特殊案例模式：返回特殊案例对象而非null（例如空列表、访客用户）
绝不返回null——返回空集合、Optional或抛出异常
绝不传递null——null参数没有合理的处理逻辑
包装第三方API，将其异常转换为你的领域异常

代码应用示例：

场景	模式	示例
返回null	返回空集合或Optional	`return Collections.emptyList()` 而非 `return null`
错误码	替换为异常	`throw new InsufficientFundsException(balance, amount)`
第三方API	使用适配器包装	`PortfolioService` 包装供应商API，转换异常
null参数	快速失败断言	`Objects.requireNonNull(user, "user must not be null")`
特殊案例	空对象模式（Null Object pattern）	`GuestUser` 提供默认行为，而非null检查
错误上下文	包含操作+状态	`"Failed to save invoice #1234 for customer 'Acme'"`

参考：references/error-handling.md

5. Unit Testing

5. 单元测试

Core concept: Tests are first-class code. They must be clean, readable, and maintained with the same discipline as production code. Dirty tests are worse than no tests -- they become a liability that slows every change.

Why it works: Clean tests serve as executable documentation, showing exactly how the system is intended to behave. They provide a safety net for refactoring and a regression check for every change. Without tests, every modification is a potential bug. With dirty tests, every modification requires fighting through incomprehensible test code.

Key insights:

The Three Laws of TDD: (1) write a failing test first, (2) write only enough test to fail, (3) write only enough code to pass
One concept per test -- not necessarily one assert, but one logical assertion
Tests should be readable: use the Build-Operate-Check pattern (Arrange-Act-Assert)
F.I.R.S.T. principles: Fast, Independent, Repeatable, Self-validating, Timely
Test names should describe the scenario and expected behavior
Test code deserves the same refactoring attention as production code
Domain-specific testing language: build helper functions that read like a DSL

Code applications:

Context	Pattern	Example
Test structure	Arrange-Act-Assert	Setup, execute, verify -- clearly separated
Test naming	Scenario + expected behavior	`shouldRejectExpiredToken` not `test1`
Shared setup	Extract builder/factory	`aUser().withRole(ADMIN).build()`
Multiple scenarios	Parameterized tests	One test method, multiple input/output pairs
Flaky tests	Remove external dependencies	Mock time, network, file system
Test readability	Domain-specific helpers	`assertThatInvoice(inv).isPaidInFull()`

See: references/testing-principles.md

核心概念： 测试是一等代码。它们必须像生产代码一样整洁、可读且被维护。混乱的测试比没有测试更糟——它们会成为阻碍所有变更的负担。

作用： 整洁的测试可作为可执行文档，准确展示系统的预期行为。它们为重构提供安全网，为每个变更提供回归检查。没有测试，每次修改都可能引入bug。有混乱的测试，每次修改都要费力处理难以理解的测试代码。

关键要点：

TDD三定律：(1) 先编写失败的测试；(2) 只编写足够导致失败的测试代码；(3) 只编写足够让测试通过的生产代码
每个测试对应一个概念——不一定是一个断言，但要是一个逻辑断言
测试应可读：使用构建-操作-检查模式（Arrange-Act-Assert）
F.I.R.S.T.原则：快速（Fast）、独立（Independent）、可重复（Repeatable）、自验证（Self-validating）、及时（Timely）
测试名称应描述场景和预期行为
测试代码应像生产代码一样被重视和重构
领域特定测试语言：构建读起来像DSL的辅助函数

代码应用示例：

场景	模式	示例
测试结构	Arrange-Act-Assert	准备、执行、验证——清晰分离
测试命名	场景+预期行为	`shouldRejectExpiredToken` 而非 `test1`
共享准备逻辑	提取构建器/工厂	`aUser().withRole(ADMIN).build()`
多场景	参数化测试	一个测试方法，多组输入/输出对
不稳定测试	移除外部依赖	模拟时间、网络、文件系统
测试可读性	领域特定辅助函数	`assertThatInvoice(inv).isPaidInFull()`

参考：references/testing-principles.md

6. Code Smells and Heuristics

6. 代码异味与启发式规则

Core concept: Code smells are surface indicators of deeper design problems. Learn to recognize them quickly and apply targeted refactorings. Not every smell requires immediate action, but ignoring them accumulates technical debt.

Why it works: Smells are heuristics -- they point toward likely problems without requiring deep analysis. A developer who can quickly identify "this function has too many arguments" or "this class has feature envy" can make targeted improvements instead of vague "cleanup" efforts.

Key insights:

Comments: inappropriate information, obsolete comments, redundant comments that repeat the code
Functions: too many arguments, output arguments, flag arguments, dead functions never called
General: obvious duplication, code at wrong level of abstraction, feature envy (method uses another class more than its own), magic numbers
Names: names at wrong abstraction level, names that don't describe side effects, ambiguous short names
Tests: insufficient tests, skipped tests, untested boundary conditions, no failure-path tests
Apply the Boy Scout Rule: leave code cleaner than you found it
Refactor in small, tested steps -- never refactor and add features simultaneously

Code applications:

Context	Pattern	Example
Duplication	Extract shared logic	Common validation → `validateEmail()` helper
Long parameter list	Introduce parameter object	`SearchCriteria` groups related params
Feature envy	Move method to data's class	`order.calculateTotal()` not `calculator.total(order)`
Dead code	Delete it	Remove unused functions, unreachable branches
Magic numbers	Named constants	`MAX_LOGIN_ATTEMPTS = 5` not bare `5`
Shotgun surgery	Consolidate related changes	Group scattered logic into a single module

See: references/code-smells.md

核心概念： 代码异味是深层设计问题的表面迹象。学会快速识别它们，并应用针对性的重构。并非所有异味都需要立即处理，但忽略它们会积累技术债务。

作用： 异味是启发式规则——它们无需深入分析就能指出潜在问题。能快速识别「这个函数参数太多」或「这个类有特性羡慕」的开发者，可以进行针对性改进，而非模糊的「清理」工作。

关键要点：

注释：信息不当、过时、重复代码的冗余注释
函数：参数过多、输出参数、标志参数、从未被调用的死函数
通用问题：明显的重复、抽象层级错误的代码、特性羡慕（方法使用其他类的频率高于自身类）、魔数
命名：抽象层级错误的名称、未描述副作用的名称、模糊的短名称
测试：测试不足、跳过的测试、未测试的边界条件、无失败路径测试
应用童子军规则：让代码比你接手时更整洁
以小的、经过测试的步骤进行重构——绝不要同时重构和添加功能

代码应用示例：

场景	模式	示例
重复代码	提取共享逻辑	通用验证逻辑→ `validateEmail()` 辅助函数
长参数列表	引入参数对象	`SearchCriteria` 分组相关参数
特性羡慕	将方法移到数据所属的类	`order.calculateTotal()` 而非 `calculator.total(order)`
死代码	删除它	移除未使用的函数、不可达的分支
魔数	命名常量	`MAX_LOGIN_ATTEMPTS = 5` 而非裸值 `5`
霰弹式修改	整合相关变更	将分散的逻辑分组到单个模块

参考：references/code-smells.md

Common Mistakes

常见错误

Mistake	Why It Fails	Fix
Abbreviating names	Saves seconds writing, costs hours reading	Use full, descriptive names; IDEs autocomplete
"Clever" one-liners	Impressive to write, impossible to debug	Expand into readable steps with clear names
Comments instead of refactoring	Comments rot; code is the truth	Extract well-named function instead of commenting
Catching generic exceptions	Swallows bugs along with expected errors	Catch specific exceptions, let unexpected ones propagate
No tests for error paths	Happy path works, edge cases crash	Test every branch, boundary, and failure mode
Premature optimization	Obscures intent for marginal performance	Write clean code first, optimize measured bottlenecks
God classes	One class, 2000 lines, does everything	Apply SRP -- split by responsibility
Refactoring without tests	No safety net to catch regressions	Write characterization tests before refactoring
Inconsistent conventions	Every file feels like a different codebase	Agree on style, enforce with linters and formatters
Returning null everywhere	Null checks spread like a virus	Use Optional, empty collections, or Null Object pattern

错误	失败原因	修复方案
缩写名称	编写时节省几秒，阅读时浪费数小时	使用完整、描述性的名称；IDE会自动补全
「聪明」的单行代码	编写时让人印象深刻，调试时几乎不可能	拆分为可读的步骤并使用清晰的名称
用注释代替重构	注释会过时；代码才是真相	提取命名清晰的函数而非编写注释
捕获通用异常	同时吞掉bug和预期错误	捕获特定异常，让意外异常传播
错误路径无测试	主流程正常，但边缘场景崩溃	测试每个分支、边界和失败模式
过早优化	为了微小的性能损失代码意图	先编写整洁的代码，再优化经测量的瓶颈
上帝类	一个类2000行代码，包揽所有功能	应用单一职责原则（SRP）——按职责拆分
无测试重构	没有安全网捕获回归问题	重构前先编写特征测试
不一致的规范	每个文件都像不同的代码库	达成风格共识，用代码检查工具和格式化工具强制执行
到处返回null	null检查像病毒一样扩散	使用Optional、空集合或空对象模式

Quick Diagnostic

快速诊断

Audit any codebase:

Question	If No	Action
Can you understand each function without reading its body?	Names don't reveal intent	Rename functions to describe what they do
Are all functions under 20 lines?	Functions do too many things	Extract sub-operations into named helpers
Are there zero commented-out code blocks?	Dead code creating confusion	Delete them -- version control has history
Is error handling separate from business logic?	Try-catch blocks cluttering main flow	Extract error handling; use exceptions not return codes
Does every class have a single responsibility?	Classes accumulate unrelated duties	Split into focused classes with clear names
Is there a test for every public method?	No safety net for changes	Add tests before making further changes
Are test names descriptive of behavior?	Tests are hard to understand when they fail	Rename to `shouldDoXWhenY` pattern
Is duplication below 3 occurrences?	Copy-paste spreading bugs	Extract into shared function or module
Are magic numbers replaced with named constants?	Intent is hidden behind raw values	Extract constants with descriptive names
Can you run all tests in under 10 seconds?	Slow tests discourage running them	Mock external deps, split integration tests

审核任意代码库：

问题	如果答案为否	行动
无需阅读函数体就能理解每个函数的功能？	名称未传达意图	重命名函数以描述其功能
所有函数都在20行以内？	函数职责过多	将子操作提取为命名辅助函数
没有被注释掉的代码块？	死代码造成混淆	删除它们——版本控制系统有历史记录
错误处理与业务逻辑分离？	try-catch块打乱主流程	提取错误处理逻辑；使用异常而非返回码
每个类都有单一职责？	类积累了无关职责	拆分为职责明确、名称清晰的类
每个公共方法都有对应的测试？	变更没有安全网	在进行进一步变更前添加测试
测试名称能描述行为？	测试失败时难以理解原因	重命名为 `shouldDoXWhenY` 模式
重复代码少于3处？	复制粘贴传播bug	提取为共享函数或模块
魔数都被替换为命名常量？	意图被原始值隐藏	提取带描述性名称的常量
所有测试能在10秒内运行完成？	缓慢的测试会阻碍开发者运行它们	模拟外部依赖，拆分集成测试

Reference Files

参考文件

naming-conventions.md: Intention-revealing names, avoiding disinformation, class vs. method naming, before/after examples
functions-and-methods.md: Small functions, argument counts, command-query separation, the step-down rule, side effects
comments-formatting.md: Good vs. bad comments, the newspaper metaphor, vertical formatting, team rules
error-handling.md: Exceptions over return codes, null handling, Special Case pattern, wrapping third-party APIs
testing-principles.md: TDD laws, F.I.R.S.T. principles, clean test patterns, test readability
code-smells.md: Comprehensive smell catalog organized by category, with targeted refactorings

naming-conventions.md：传达意图的命名、避免误导、类与方法命名、前后示例
functions-and-methods.md：短小函数、参数数量、命令查询分离、自上而下规则、副作用
comments-formatting.md：好注释与坏注释、报纸隐喻、垂直格式、团队规则
error-handling.md：异常优先于返回码、null处理、特殊案例模式、包装第三方API
testing-principles.md：TDD定律、F.I.R.S.T.原则、整洁测试模式、测试可读性
code-smells.md：按类别组织的全面异味目录，附针对性重构方案

About the Author

关于作者

Robert C. Martin ("Uncle Bob") is a software engineer, instructor, and author who has been programming since 1970. He is a co-author of the Agile Manifesto and the founder of Uncle Bob Consulting LLC and Clean Coders. His books -- Clean Code (2008), The Clean Coder (2011), Clean Architecture (2017), and Clean Agile (2019) -- have shaped how an entire generation of developers think about code quality, professional responsibility, and software design. Martin is known for his uncompromising stance that developers are professionals who must take responsibility for the quality of their work, and that the only way to go fast is to go well.

Robert C. Martin（「鲍勃大叔」）是一名软件工程师、讲师和作家，自1970年开始编程。他是敏捷宣言的合著者，也是Uncle Bob Consulting LLC和Clean Coders的创始人。他的著作——《Clean Code》（2008）、《The Clean Coder》（2011）、《Clean Architecture》（2017）和《Clean Agile》（2019）——塑造了整整一代开发者对代码质量、职业责任和软件设计的思考。Martin以其坚定的立场著称：开发者是专业人士，必须对自己工作的质量负责，而快速交付的唯一途径是高质量的工作。

clean-code

Original

Translation

Clean Code Framework

整洁代码框架

Core Principle

核心原则

Scoring

评分标准

The Clean Code Framework

整洁代码框架

1. Meaningful Names

1. 有意义的命名

2. Functions

2. 函数

3. Comments and Formatting

3. 注释与格式

4. Error Handling

4. 错误处理

5. Unit Testing

5. 单元测试

6. Code Smells and Heuristics

6. 代码异味与启发式规则

Common Mistakes

常见错误

Quick Diagnostic

快速诊断

Reference Files

参考文件

Further Reading

延伸阅读

About the Author

关于作者