---

name: clean-code description: "本技能体现了Robert C. Martin（Uncle Bob）《代码整洁之道》的原则。用它将'能运行的代码'转变为'整洁的代码'。" risk: safe source: "ClawForge (https://github.com/jackjin1997/ClawForge)" date_added: "2026-02-27"

代码整洁之道技能

本技能体现了Robert C. Martin（Uncle Bob）《代码整洁之道》的原则。用它将"能运行的代码"转变为"整洁的代码"。

核心哲学

"如果代码能被原作者之外的开发者阅读和改进，那它就是整洁的。" — Grady Booch

何时使用

在以下情况使用本技能：

• 编写新代码：从一开始确保高质量。
• 审查Pull Request：提供建设性的、基于原则的反馈。
• 重构遗留代码：识别和消除代码异味。
• 改善团队标准：对齐行业标准最佳实践。

1. 有意义的命名

• 使用揭示意图的名称：elapsedTimeInDays 而非 d。
• 避免误导：如果实际是 Map，不要用 accountList。
• 做有意义的区分：避免 ProductData vs ProductInfo。
• 使用可发音/可搜索的名称：避免 genymdhms。
• 类名：使用名词（Customer、WikiPage）。避免 Manager、Data。
• 方法名：使用动词（postPayment、deletePage）。

2. 函数

• 短小！：函数应该比你想象的更短。
• 只做一件事：函数应该只做一件事，并且做好。
• 一个抽象层级：不要将高层业务逻辑与低层细节混合。
• 描述性名称：isPasswordValid 优于 check。
• 参数：0个是理想的，1-2个可以，3个以上需要非常充分的理由。
• 无副作用：函数不应暗中改变全局状态。

3. 注释

• 不要注释糟糕的代码——重写它：大多数注释是我们未能在代码中表达自己的标志。
• 在代码中解释自己：

  # Check if employee is eligible for full benefits
  if employee.flags & HOURLY and employee.age > 65:
  

  对比

  if employee.isEligibleForFullBenefits():
  

• 好的注释：法律声明、信息性、澄清、TODO。
• 坏的注释：含糊不清、冗余、误导、强制性、噪音、位置标记。

4. 格式化

• 报纸隐喻：高层概念在顶部，细节在底部。
• 垂直密度：相关的行应该彼此靠近。
• 距离：变量应在其使用处附近声明。

5. 对象和数据结构

• 数据抽象：将实现隐藏在接口后面。
• 迪米特法则：避免 a.getB().getC().doSomething()。
• DTO：具有公共变量且无函数的类。

6. 错误处理

• 使用异常而非返回码
• 先写try-catch-finally
• 提供异常的上下文
• 不要返回null
• 不要传递null

7. 单元测试

• F.I.R.S.T.：快速、独立、可重复、自验证、及时。
• 每个测试一个概念
• 测试代码和生产代码同等重要

8. 类

• 单一职责原则：类应该只有一个改变的理由。
• 高内聚：方法应该操作类的实例变量。
• 开闭原则：对扩展开放，对修改关闭。

9. 代码异味速查

| 异味 | 修复 | |------|------| | 过长函数 | 提取方法 | | 过多参数 | 引入参数对象 | | 重复代码 | 提取公共方法 | | 特性嫉妒 | 移动方法 | | 数据泥团 | 创建封装类 | | 开关语句 | 多态替代 |