---
name: clean-code-zh
description: 遵循 Robert C. Martin 的《代码整洁之道》原则，进行代码审查、重构和编写。涵盖命名、函数、注释和错误处理的最佳实践。
tags: [重构, 代码质量, 软件工程, 最佳实践, clean-code]
risk: low
source: Robert C. Martin (Clean Code)
---

# 代码整洁之道 (Clean Code)

本技能赋能 AI Agent 编写、审查和重构符合 **Robert C. Martin (Uncle Bob)**《代码整洁之道》原则的代码。其核心目标是提高代码的可读性、可维护性和长期生产力。

## 核心原则

### 1. 有意义的命名
- **名副其实**：变量、函数或类的名称应说明其存在的意义、功能以及用法。
- **避免误导**：避免使用具有特定编程含义的词（如 `accountList` 除非它真的是 `List`）。
- **做有意义的区分**：避免使用 `data1`, `data2` 或 `theMessage` 这样模糊的命名。
- **使用读得出来的名称**：避免使用缩写（如 `genymdhms` -> `generationTimestamp`）。
- **使用可搜索的名称**：单字母变量仅限用于短小的循环内部。

### 2. 函数
- **短小**：函数的第一条规则是短小。第二条规则是还要更短小。
- **只做一件事**：函数应该做一件事，做好这件事，且只做这一件事。
- **每个函数一个抽象层级**：确保函数内的语句都在同一抽象层级上。
- **函数参数**：最理想的参数数量是 0，其次是 1，再次是 2。尽量避免 3 个及以上参数。
- **无副作用**：函数不应在暗地里修改全局变量或对象状态。
- **分隔指令与询问**：函数要么执行某项动作，要么回答某个问题，不应兼而有之。

### 3. 注释
- **注释不能美化糟糕的代码**：代码应当能自解释。如果需要注释，首先考虑是否可以通过重构来消除注释。
- **好的注释**：法律信息、对意图的解释、警示后果、TODO 注释。
- **糟糕的注释**：喃喃自语、冗余注释、误导性注释、日志式注释、署名注释、废话注释。

### 4. 格式
- **垂直距离**：关系密切的概念应在垂直方向上靠近。
- **横向格式**：代码行不应过宽（建议限制在 100-120 字符以内）。
- **团队规则**：始终遵循团队约定的格式规范。

### 5. 错误处理
- **使用异常而非返回码**：返回码会导致调用者逻辑混乱。
- **先写 Try-Catch-Finally 语句**：这有助于定义程序的范围。
- **不要返回 null**：返回空集合或抛出异常，以避免到处都是空检查。
- **不要传递 null**：除非 API 明确要求，否则禁止向函数传递 null。

### 6. 类
- **单一权责原则 (SRP)**：一个类应该只有一个导致其变化的原因。
- **内聚性**：类应该只有少量的实体变量，方法应操作这些变量。
- **为了修改而组织**：类应该对扩展开放，对修改关闭 (OCP)。

## 何时使用 (When to Use)

- **编写新功能**：确保初始实现符合整洁标准。
- **代码审查 (Code Review)**：识别违反整洁原则的模式。
- **技术债重构**：将“能跑就行”的代码转化为专业级代码。
- **API 设计**：创建直观且自解释的接口。

## 审查清单 (Review Checklist)

1. 名称是否表达了意图？
2. 函数是否超过了 20 行？
3. 函数是否混合了多个抽象层级？
4. 是否可以通过重命名变量来消除某段注释？
5. 是否使用了异常处理而非 if/else 返回错误码？
6. 类是否过于庞大（违反 SRP）？