代码整洁之道 (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)
- 名称是否表达了意图？
- 函数是否超过了 20 行？
- 函数是否混合了多个抽象层级？
- 是否可以通过重命名变量来消除某段注释？
- 是否使用了异常处理而非 if/else 返回错误码？
- 类是否过于庞大（违反 SRP）？