clean-code

Clean Code 技能

这项技能体现了 Robert C. Martin（Uncle Bob）的“Clean Code”原则。使用它将“能运行的代码”转变为“整洁的代码”。

🧠 核心理念

“如果开发者（而非代码的原作者）能够阅读并改进代码，那么代码就是整洁的。”—— Grady Booch

1. 有意义的命名

• 使用能体现意图的名称：使用 elapsedTimeInDays，而不是 d。
• 避免误导：如果实际类型是 Map，就不要使用 accountList。
• 区分应有意义：避免使用 ProductData 和 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。
• 不要传入 Null：这会导致 NullPointerException。

7. 单元测试

• TDD 三定律：
  1. 在有失败的单元测试之前，不要编写生产代码。
  2. 编写的单元测试只要足以失败即可，不要多写。
  3. 编写的生产代码只要足以通过失败的测试即可，不要多写。
• F.I.R.S.T. 原则：快速、独立、可重复、自我验证、及时。

8. 类

• 要小！：类应该只有一个职责（SRP）。
• 逐步深入规则：我们希望代码读起来像一篇自上而下展开的叙述。

9. 异味与启发式原则

• 僵化性：难以修改。
• 脆弱性：在许多地方都会出错。
• 不可移动性：难以复用。
• 黏滞性：难以采取正确的做法。
• 不必要的复杂性／重复。

🛠️ 实施检查清单

• 这个函数是否少于 20 行？
• 这个函数是否只做一件事？
• 所有名称是否都易于搜索且能体现意图？
• 我是否通过让代码更清晰来避免添加注释？
• 我传入的参数是否过多？
• 这个改动是否有对应的失败测试？