> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt
> Use this file to discover all available pages before exploring further.

# clean-code-zh

> 遵循 Robert C. Martin 的《代码整洁之道》原则，进行代码审查、重构和编写。涵盖命名、函数、注释和错误处理的最佳实践。

| 项目 | 内容                                                                                                                                                                                                                                                                   |
| -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 来源 | [skills/clean-code-zh/SKILL.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/clean-code-zh/SKILL.md)                                                                                                                             |
| 分类 | 开发工程 & 工作流                                                                                                                                                                                                                                                           |
| 安装 | 克隆 [Skill 分支](https://github.com/new-energy-coder-club/new_energy_coder_club/tree/Skill) 后，将 `skills/clean-code-zh/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 [Skill 安装方式](/community/skill-branch) |

# 代码整洁之道 (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）？