clean-code

Clean Code 技能

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

🧠 核心理念

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

适用场景

在以下情况下使用这项技能：

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

这些是设计启发式原则，并非普遍适用的语言规则，也不代表可以随意更改行为。遵循实际的代码仓库约定；是否使用异常而非结果类型、如何处理可空性、参数数量和测试频率，都取决于语言和任务。保留必要的理由说明、安全和许可证注释。只在范围内进行重构，并验证相关行为。

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. 原则：快速（Fast）、独立（Independent）、可重复（Repeatable）、自验证（Self-Validating）、及时（Timely）。

8. 类

• 越小越好！：类应遵循单一职责原则（SRP）。
• 逐步深入规则：我们希望代码读起来像一篇由上而下展开的叙述。

9. 代码异味与启发式原则

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

🛠️ 实现检查清单

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

示例

用户请求：

重构这段可正常运行的代码，让名称更清晰、单元更小、错误更明确，同时保留原有行为；并通过针对性测试进行验证。

限制

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