clean-code

整洁代码

在此技能启用期间，你编写、修改或审查的任何代码都必须遵守以下工程标准。这些标准与语言无关：无论项目使用哪种语言，都应遵循，同时尊重该语言的惯用写法。

如果速度与整洁性发生冲突，除非出现已证实的运行紧急情况，否则应选择整洁的方案。如果无法避免走捷径，应将其限制在最小范围内，让它显而易见，并确保代码之后可以安全地清理。

如需了解详细的理由、示例和设计启发式，请阅读 reference.md——当规则需要解释，或遇到不明显的设计决策时，请查阅。

核心规则

1. 让代码变得更整洁

每项修改都必须至少改善以下一项：清晰度、命名、简洁性、内聚性、可测试性、错误处理、重复消除或关注点分离。不要只添加能运行的代码——要添加易于理解的代码。

2. 为读者优化

• 为下一位工程师编写代码，而不是为了炫技。
• 优先选择直白的代码，而不是巧妙的代码。
• 让控制流一目了然。
• 如果代码很难解释，就将其视为设计问题。

3. 使用明确的名称

• 名称必须体现意图。始终如一地使用领域语言。
• 优先使用具体名称，避免使用 data、info、thing、stuff、manager、helper、util、misc、handle、temp、obj，除非它们确实符合领域含义或外部协议。
• 布尔名称应读起来像谓词（active?、isActive、hasItems、retryable?），并遵循语言惯例。
• 集合名称使用复数形式。
• 函数名称应描述所执行的操作，而不是含糊的活动（calculate_invoice_total，而不是 do_invoice）。

4. 保持方法小巧且专注

• 一个方法应在同一抽象层级上只做一件事。
• 不要在一个方法中混合业务规则、格式化、持久化、外部调用和错误恢复。如果一个方法包含多个阶段，应提取辅助方法。
• 参数数量优先为零个、一个或两个；三个参数应引起审视；更多参数通常意味着缺少值对象或领域对象。
• 如果单独的方法能更清楚地表达意图，就不要使用布尔参数来切换行为。

5. 分开不同抽象层级

• 不要在一个方法中混合高层策略与底层机制。
• 将编排与实现细节分开，并将领域逻辑与 I/O、框架粘合代码和序列化分开。

6. 明确副作用

• 避免同时回答问题并执行操作的方法。
• 副作用必须体现在名称和位置上；避免隐藏式变更。
• 优先使用显式依赖，而不是隐式全局变量。

7. 控制条件逻辑

• 优先使用守卫子句，而不是深层嵌套；让分支保持浅层。
• 将复杂谓词提取为能体现意图的名称。
• 避免在多个位置重复条件逻辑。
• 条件表达清晰时，优先使用肯定条件。

8. 将错误视为设计的一部分

• 对无效假设快速失败；不要悄无声息地吞掉错误。
• 抛出或返回错误时，提供有用的诊断上下文。
• 保持正常路径易于阅读。
• 不要无故混淆验证错误、领域错误和基础设施故障。

9. 保持模块和类的内聚性

• 每个单元都应只有一个明确的变更原因。保持公开接口精简。
• 避免上帝对象、上帝模块和包罗万象的工具命名空间。
• 优先使用组合，避免错综复杂的继承。

10. 在恰当的层级消除重复

• 消除重复的逻辑、决策、业务规则和有意义的字面值。
• 不要为了合并表面相似的代码行而过早引入不稳定的抽象。应在意义恰当的层级消除重复。

11. 先测试后开发

• 默认采用测试驱动开发。更改行为、修复 Bug 或添加功能时，先编写或更新一个失败的测试。
• 测试行为，而非偶然的实现细节。
• 测试必须易读、结果确定、不受执行顺序影响，并以预期结果命名。保持准备工作简洁，并清楚体现意图。
• 只要实际可行，就在修复 Bug 之前添加回归测试。
• 如果确实因缺少测试框架或遗留限制而无法严格遵循测试优先，请明确说明，并立即添加最接近且有用的测试覆盖，让相关部分比之前更易于测试。

12. 边工作边重构

• 改进含义不明的名称，拆分过长的方法，并删除你所处理区域中的无用代码。
• 重构时确保测试持续通过。
• 如果无法全面清理，就改进最近的有意义边界，并留下清晰说明。

13. 遵循语言习惯，但不要掩盖意图

• 只有在目标语言的专业工程师能够一目了然时，才使用该语言的惯用写法。
• 优先使用简洁、清晰的代码单元，而非共享可变状态的过程式脚本。
• 如果普通代码在调用处和定义处都更清晰，就避免使用元编程、魔法或 DSL。
• 将数据库、API、队列和框架等外部系统隔离在清晰的边界后，避免供应商特定知识到处渗透。

14. 完成标准

只有满足以下条件，任务才算完成：

• 实现正确
• 设计易于理解，名称清晰
• 修改过的代码比之前更整洁
• 存在相关测试且测试通过（除非注明确有实际限制，否则应遵循测试优先）
• 修改区域中没有明显的重复代码或无用代码