clean-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Robert C. Martin (Uncle Bob) Clean Code Best Practices

Robert C. Martin（鲍勃大叔）Clean Code最佳实践

Comprehensive software craftsmanship guide based on Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship". Contains 45 rules across 8 categories, prioritized by impact to guide code reviews, refactoring decisions, and new development.

这是基于Robert C. Martin所著《Clean Code: A Handbook of Agile Software Craftsmanship》的综合性软件工艺指南。包含8个类别共45条规则，按影响优先级排序，可指导代码评审、重构决策和新代码开发。

When to Apply

适用场景

Reference these guidelines when:

Writing new functions, classes, or modules
Naming variables, functions, classes, or files
Reviewing code for maintainability issues
Refactoring existing code to improve clarity
Writing or improving unit tests

在以下场景中参考这些指南：

编写新函数、类或模块
为变量、函数、类或文件命名
评审代码以排查可维护性问题
重构现有代码以提升清晰度
编写或优化单元测试

Rule Categories by Priority

按优先级划分的规则类别


name-
func-
cmt-
fmt-
obj-
err-
test-
class-

Priority	Category	Impact	Prefix
1	Meaningful Names	CRITICAL	`name-`
2	Functions	CRITICAL	`func-`
3	Comments	HIGH	`cmt-`
4	Formatting	HIGH	`fmt-`
5	Objects and Data Structures	MEDIUM-HIGH	`obj-`
6	Error Handling	MEDIUM-HIGH	`err-`
7	Unit Tests	MEDIUM	`test-`
8	Classes and Systems	MEDIUM	`class-`


name-
func-
cmt-
fmt-
obj-
err-
test-
class-

优先级	类别	影响程度	前缀
1	有意义的命名	关键	`name-`
2	函数	关键	`func-`
3	注释	高	`cmt-`
4	格式	高	`fmt-`
5	对象与数据结构	中高	`obj-`
6	错误处理	中高	`err-`
7	单元测试	中	`test-`
8	类与系统	中	`class-`

Quick Reference

快速参考

1. Meaningful Names (CRITICAL)

1. 有意义的命名（关键）

```
name-intention-revealing
```
- Use names that reveal intent
```
name-avoid-disinformation
```
- Avoid misleading names
```
name-meaningful-distinctions
```
- Make meaningful distinctions
```
name-pronounceable
```
- Use pronounceable names
```
name-searchable
```
- Use searchable names
```
name-avoid-encodings
```
- Avoid encodings in names
```
name-class-noun
```
- Use noun phrases for class names
```
name-method-verb
```
- Use verb phrases for method names

```
name-intention-revealing
```
- 使用能体现意图的命名
```
name-avoid-disinformation
```
- 避免误导性命名
```
name-meaningful-distinctions
```
- 做出有意义的区分
```
name-pronounceable
```
- 使用易读的命名
```
name-searchable
```
- 使用便于搜索的命名
```
name-avoid-encodings
```
- 避免在命名中使用编码
```
name-class-noun
```
- 类名使用名词短语
```
name-method-verb
```
- 方法名使用动词短语

2. Functions (CRITICAL)

2. 函数（关键）

```
func-small
```
- Keep functions small
```
func-one-thing
```
- Functions should do one thing
```
func-abstraction-level
```
- Maintain one level of abstraction
```
func-minimize-arguments
```
- Minimize function arguments
```
func-no-side-effects
```
- Avoid side effects
```
func-command-query-separation
```
- Separate commands from queries
```
func-prefer-exceptions
```
- Prefer exceptions to error codes
```
func-dry
```
- Do not repeat yourself

```
func-small
```
- 保持函数简洁
```
func-one-thing
```
- 函数应该只做一件事
```
func-abstraction-level
```
- 保持单一抽象层级
```
func-minimize-arguments
```
- 尽量减少函数参数
```
func-no-side-effects
```
- 避免副作用
```
func-command-query-separation
```
- 分离命令与查询
```
func-prefer-exceptions
```
- 优先使用异常而非错误码
```
func-dry
```
- 不要重复自己（DRY原则）

3. Comments (HIGH)

3. 注释（高）

```
cmt-express-in-code
```
- Express yourself in code, not comments
```
cmt-explain-intent
```
- Use comments to explain intent
```
cmt-avoid-redundant
```
- Avoid redundant comments
```
cmt-avoid-commented-out-code
```
- Delete commented-out code
```
cmt-warning-consequences
```
- Use warning comments for consequences

```
cmt-express-in-code
```
- 用代码表达，而非注释
```
cmt-explain-intent
```
- 使用注释解释意图
```
cmt-avoid-redundant
```
- 避免冗余注释
```
cmt-avoid-commented-out-code
```
- 删除被注释掉的代码
```
cmt-warning-consequences
```
- 使用警告注释说明后果

4. Formatting (HIGH)

4. 格式（高）

```
fmt-vertical-formatting
```
- Use vertical formatting for readability
```
fmt-horizontal-alignment
```
- Avoid horizontal alignment
```
fmt-team-rules
```
- Follow team formatting rules
```
fmt-indentation
```
- Respect indentation rules

```
fmt-vertical-formatting
```
- 使用垂直格式提升可读性
```
fmt-horizontal-alignment
```
- 避免水平对齐
```
fmt-team-rules
```
- 遵循团队格式规则
```
fmt-indentation
```
- 遵守缩进规则

5. Objects and Data Structures (MEDIUM-HIGH)

5. 对象与数据结构（中高）

```
obj-data-abstraction
```
- Hide data behind abstractions
```
obj-data-object-asymmetry
```
- Understand data/object anti-symmetry
```
obj-law-of-demeter
```
- Follow the Law of Demeter
```
obj-avoid-hybrids
```
- Avoid hybrid data-object structures
```
obj-dto
```
- Use DTOs for data transfer

```
obj-data-abstraction
```
- 用抽象隐藏数据
```
obj-data-object-asymmetry
```
- 理解数据/对象的不对称性
```
obj-law-of-demeter
```
- 遵循Law of Demeter（迪米特法则）
```
obj-avoid-hybrids
```
- 避免混合数据-对象结构
```
obj-dto
```
- 使用DTO进行数据传输

6. Error Handling (MEDIUM-HIGH)

6. 错误处理（中高）

```
err-use-exceptions
```
- Use exceptions instead of return codes
```
err-write-try-catch-first
```
- Write try-catch-finally first
```
err-provide-context
```
- Provide context with exceptions
```
err-define-by-caller-needs
```
- Define exceptions by caller needs
```
err-avoid-null
```
- Avoid returning and passing null

```
err-use-exceptions
```
- 使用异常而非返回码
```
err-write-try-catch-first
```
- 先编写try-catch-finally块
```
err-provide-context
```
- 为异常提供上下文信息
```
err-define-by-caller-needs
```
- 根据调用者需求定义异常
```
err-avoid-null
```
- 避免返回和传递null

7. Unit Tests (MEDIUM)

7. 单元测试（中）

```
test-first-law
```
- Follow the three laws of TDD
```
test-keep-clean
```
- Keep tests clean
```
test-one-assert
```
- One assert per test
```
test-first-principles
```
- Follow FIRST principles
```
test-build-operate-check
```
- Use Build-Operate-Check pattern

```
test-first-law
```
- 遵循TDD的三条法则
```
test-keep-clean
```
- 保持测试代码整洁
```
test-one-assert
```
- 每个测试只包含一个断言
```
test-first-principles
```
- 遵循FIRST原则
```
test-build-operate-check
```
- 使用Build-Operate-Check模式

8. Classes and Systems (MEDIUM)

8. 类与系统（中）

```
class-small
```
- Keep classes small
```
class-cohesion
```
- Maintain class cohesion
```
class-organize-for-change
```
- Organize classes for change
```
class-isolate-from-change
```
- Isolate classes from change
```
class-separate-concerns
```
- Separate construction from use

```
class-small
```
- 保持类的简洁
```
class-cohesion
```
- 保持类的内聚性
```
class-organize-for-change
```
- 为变更组织类结构
```
class-isolate-from-change
```
- 将类与变更隔离开
```
class-separate-concerns
```
- 分离构造与使用

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细解释和代码示例：

章节定义 - 类别结构和影响级别
规则模板 - 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息