clean-code

Clean Code

代码是供人阅读、修改和删除的。运行四项检查：设计、命名、复杂度、注释。每项都有明确标准，而不是凭感觉。

路由到子技能

对于函数、类或文件内保持行为不变的重构，请阅读 refactoring/SKILL.md。其中提供了代码异味目录、技术选择器 和防护措施。行为变更时（testing（TCRDD 参考））或跨文件依赖梳理时 （mikado-method），不要使用它。

1. 设计出便于人理解的心智模型

在同一种需求独立出现至少三次之前，优先采用具体方案。抽象编写起来很便宜，但之后每位读者都要花时间学习和追踪。假设未来可能有某种需求，并不是添加抽象的理由。

在缺陷的根因处修复，而不是围绕症状再添加一个特殊情况分支。好的修复应减少代码中的路径，或修复导致问题的共享规则。

代码块是边界容器——仓库 → 服务 → 模块 → 函数——让读者可以忽略任务范围之外的内容。让每个代码块保持足够连贯，以便在局部理解。切片会横跨这些边界：可观测性、可恢复性、无障碍性、安全性及类似关注点。让它们经过受影响代码块的路径容易查找和追踪；不要为了让单个代码块看起来整洁，就隐藏横切关注点。

有些复杂性属于领域本身。不要把税务、合规或其他真实规则简化成看似简单却不正确的模型。应优先选择新读者无需额外背景就能正确理解的设计，而不只是选择表达最简短的设计。

2. 命名

每个模块、文件、函数、类和变量的名称都必须独立体现意图——无需阅读主体即可知道它的作用。

按以下顺序进行检查：

1. 体现意图：名称说明它做什么或保存什么，而不是如何实现（elapsedTimeInDays，而不是 d）。如果需要注释来解释名称，那这个名称就不合格。
2. 避免混淆：不要使用难以区分的名称（userList 与 usersList），除非它确实是 List 类型，否则不要称它为 list。同一概念不要使用两个名称，也不要用一个名称指代两个概念。
3. 减少冗余：删去没有增加含义的冗余词——data、info、manager、object、Impl。ProductInfo 和 Product——如果二者都存在，实际使用中很难区分。优先使用较短的名称，让上下文（文件夹、类型）补充其余含义。
4. 避免使用首字母缩写和缩写词：使用 calculateInvoiceTotal，而不是 calcInvTot。例外：领域中更常用首字母缩写，而非其完整形式（id、url、html）——但要选定一种大小写惯例并保持一致。
5. 便于搜索：除了紧凑循环中的索引之外，不要使用魔法数字或单字母名称。使用 MAX_RETRY_COUNT，而不是 5 或 n。可以用 grep 搜索的名称胜过无法搜索的名称。
6. 词性：类和类型使用名词短语（Invoice、PaymentProcessor）；函数和方法使用动词短语（calculateTotal、isValid、hasExpired）。以名词命名的函数是个代码异味——它可能在返回某种结果，却没有以该结果命名，或者承担了过多职责。
7. 一个概念用一个词：整个代码库中，同一种操作统一使用一个动词——不要对同类操作混用 fetch/retrieve/get，也不要对同类变更混用 add/insert/append。引入新同义词前，先检查代码库中已有的惯例。

3. 圈复杂度

每个函数的预算：

• 人工编写的代码：≤ 4
• Agent 编写的代码（Claude/AI 生成）：≤ 6

计数方式：从 1 开始，条件中每出现一个 if、else if、case、for、while、catch、&&/|| 或三元运算符，就 +1。如果函数超出预算，应先重构，再视为完成——不要搁置不管，直接继续。

对于保持行为不变的修改，请使用重构子技能来选择合适的技术，而不是单纯为了达到预算而提取代码。

不要只为凑数而重构——整洁的 5 胜过扭曲的 4。预算是提醒你仔细检查的触发条件，不是可以钻空子的硬性门槛。

4. 注释

不必太在意。不要把注释奉为圭臬，也不要把注释数量当作衡量指标——需要靠注释才能理解的代码，通常应该先改写（使用更好的名称、提取函数）；但如果注释是表达某件事最清晰的方式，那就直接写。

• 优先使用自解释代码，而不是用注释解释代码_做了什么_。
• 注释应该解释_为什么_——例如不明显的权衡、针对外部限制的变通方案，或有意偏离“显而易见”的做法。
• 删除只是在复述代码的注释（例如，在 i++ 上方写 // increment i）。
• 过时的注释（描述代码已不再具备的行为）比没有注释更糟——发现后应立即标记删除。
• 只要包含真实信息（为何延后，最好注明由谁、何时决定），TODO 就没问题；单独的 // TODO 不值得保留。

5. CUPID 评审

当用户要求使用该框架，或要求进行广泛的设计质量评审时，使用 CUPID。首先确认语言、用途、局部惯例和评审范围。对于每项特性，引用具体代码并采用以下格式：

### C — Composable
**Rating:** 🟢 Strong / 🟡 Moderate / 🔴 Weak
**Observations:** specific code evidence
**Suggestions:** a direction-of-travel improvement

特性	关注点
可组合	精简、清晰表达意图的 API；依赖最少
Unix 哲学	对外只有一个连贯用途；副作用符合预期
可预测	行为清晰、失败范围有界、状态确定
符合惯用法	遵循语言和局部惯例；不重复造轮子
基于领域	使用领域词汇并划分领域边界，而非按框架结构组织

简洁性规则（OAOO、三次法则、YAGNI、选择最简单的方案）：简洁性原则。XP 实践（集体负责、结对、CI、毫不留情地重构）：XP 实践。 最后总结当前已经做得好的方面，以及最值得优先推进的一到三项改进。CUPID 是方向，不是合规标准：承认权衡，避免使用“违反”或“必须”。如果某项特性需要深入分析，请阅读CUPID 完整参考。

黑客精神（以好奇心和匠心驱动工程、开源贡献方式；拒绝未经授权的访问）：黑客宣言。

注意事项

• 不要把 Agent 的复杂度预算（6）应用于主要由人手工维护的代码——应确认后续由谁负责该文件，而不是看当前差异由谁编写。
• 命名与复杂度相互影响：看起来像“高复杂度”的情况，有一半其实是“命名不佳的分支隐藏了函数的实际作用”——尝试重命名，再考虑提取代码。
• 不要为了删除冗余词而追求含糊不清——Product 与 ProductInfo 是合理的精简；Product 与 ProductOwner 则不行，它们是不同概念。
• 一个概念使用一个词，应在整个代码库范围内检查，而不是只看单个文件——引入同义词前，先搜索已有动词。
• 不要强行消除领域本身带来的复杂性；应让它显式且可验证。
• CUPID 评分是评审视角，不应成为在缺乏具体设计收益时提取或拆分代码的理由。

---

基准测试

场景：.benchmarks/scenarios/clean-code-001-agent-code-review.md · 运行：2026-08-31 · 日志：.benchmarks/runs/2026-08-31/clean-code-001-agent-code-review.json

Model	Without	With	Delta
claude-opus-4-8	67%	100%	+33%
claude-sonnet-4-6	83%	100%	+17%
claude-haiku-4-5	67%	67%	+0%

PASS (run 2026-08-31)。Opus +33（67→100）；sonnet +17（83→100）；haiku 已达上限。没有回归。门槛参见 .agents/skills/skill-optimizer/rules/release-gates.md。

场景：.benchmarks/scenarios/simple-001-root-cause-fix.md · 运行：2026-08-31 · 日志：.benchmarks/runs/2026-08-31/simple-001-root-cause-fix.json

Model	Without	With	Delta
claude-opus-4-8	83%	100%	+17%
claude-sonnet-4-6	83%	100%	+17%
claude-haiku-4-5	83%	100%	+17%

SOFT PASS (run 2026-08-31)。小幅且一致的提升；没有回归。门槛参见 .agents/skills/skill-optimizer/rules/release-gates.md。

场景：.benchmarks/scenarios/clean-code-002-cupid-review.md — 合并后等待重新运行基线/启用技能测试。