clean-code

整洁代码技能

此技能体现了Robert C. Martin（Uncle Bob）《代码整洁之道》的原则。用它来将“能工作的代码”转变为“整洁的代码”。

🧠 核心理念

“代码整洁，是指能被原作者之外的开发者阅读并增强。” — Grady Booch

何时使用

在以下情况使用此技能：

• 编写新代码：确保从一开始就高质量。
• 审查拉取请求：提供有建设性、基于原则的反馈。
• 重构遗留代码：识别并消除代码坏味道。
• 提升团队标准：对齐行业最佳实践。

1. 有意义的命名

• 使用意图明确的名称：用 elapsedTimeInDays 而不是 d。
• 避免误导：如果实际上是 Map，不要用 accountList。
• 做有意义的区分：避免 ProductData 和 ProductInfo 这样的混淆。
• 使用可读/可搜索的名称：避免 genymdhms。
• 类名：使用名词（Customer、WikiPage）。避免 Manager、Data。
• 方法名：使用动词（postPayment、deletePage）。

2. 函数

• 小！：函数应该比你想象的更短。
• 只做一件事：一个函数应该只做一件事，并且做好。
• 单一抽象层次：不要混合高层业务逻辑和底层细节（如正则表达式）。
• 描述性名称：isPasswordValid 优于 check。
• 参数：0个最理想，1-2个可以，3个以上需要非常充分的理由。
• 无副作用：函数不应偷偷改变全局状态。

3. 注释

• 不要注释糟糕的代码——重写它：大多数注释是代码表达失败的标志。
• 用代码解释自己：

  # 检查员工是否有资格享受全额福利
  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行？
• [ ] 这个函数是否只做一件事？
• [ ] 所有名称是否可搜索且意图明确？
• [ ] 我是否通过使代码更清晰而避免了注释？
• [ ] 我是否传递了太多参数？
• [ ] 是否有失败的测试对应此更改？

限制

• 仅当任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。