Clean Code (Chinese)

本技能赋能 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）？