typescript-clean-code

整洁代码

十二种变更形态异味

Shotgun Surgery · Feature Envy · Data Clumps · Long Method · Divergent Change · Duplicated Code · Large Class · Long Parameter List · Primitive Obsession · Message Chains · Dead Code · Speculative Generality

你了解每一种异味及其重构方式。它们的价值在于检查清单，而非定义——没有这些名称，差异看起来“没问题”；有了它们，你就能发现其中的形态。对你审查或编写的任何变更，都检查这十二种异味。

异味目录分为四层

每一层检查不同的单元，因此能发现其他层遗漏的问题。

负载	单元	用途
references/smells/tooling.md	仓库	每次审查都先检查这一层。 哪些异味可以由代码检查工具判断，就将它们归并为一条“将此接入 CI”的发现，而不是手写二十条
references/smells/rules.md	一行、一个函数	逐行启发式规则（C/E/F/G/N/T），以及适用于全部四层的审查立场和严重程度词汇
references/smells/fowler.md	一项修改	上述十二种异味——每种都包含检测问题、TypeScript 补救方法，以及何时不应修复
references/smells/typescript.md	一种类型	TS1-TS10：any 泄漏、类型断言与验证、穷尽性、严格性标志、品牌类型

差异可以满足 rules.md 中的每条规则，形态却依然糟糕——这正是 fowler.md 的用途。审查一项变更意味着要检查全部四层。

审查立场

三条规则对输出的影响胜过目录中的任何条目。完整内容见 references/smells/rules.md →“审查立场”。

1. 只要变更改善了代码健康度，就应批准，而不是等到代码完美。没有完美的代码，只有更好的代码。
2. 无人会采取行动的正确发现也是假阳性。 广泛扫描，谨慎报告——三条可执行的发现胜过二十条虽正确却无人理会的发现。
3. 标明可忽略的润色意见。 使用 Conventional Comments 标签——issue、 suggestion、nitpick、question、praise——并注明 (blocking) / (non-blocking)。作者若无法分辨哪些评论是可选的，就会把所有评论都当成必须处理，或者全都不理。

满足以下条件时，审查即告完成： 已检查全部四层，每条保留下来的发现都带有标签，并且（对于 issue）附有修复方案，报告还说明了有多少条发现因不太可能有人采取行动而被删去。

存在争议的规则

这些参考资料中的三条规则属于存在不同观点的立场，出现时会标注为 有争议。应呈现双方观点，并优先考虑作者展现出的推理，而非数量：

• 函数长度——references/functions/rules.md 规则 1。通过“我能给每个部分命名吗？”来检测；若将“2-5 行”这一数字照字面应用，就会过度拆分。
• 注释——references/comments/rules.md。保留理由、不变量和不明显的原因；删除重复陈述和过时注释。
• G23 多态——references/smells/rules.md。对判别联合类型使用穷尽式 switch 是符合 TypeScript 惯例的写法，不是异味。

工作流

加载 workflow.md，然后按顺序加载其中的步骤文件。每个步骤都会列出所需的参考资料，并更新输出文档 frontmatter 中的 stepsCompleted，因此压缩上下文后可通过 step-01b-continue.md 从上次完成的步骤继续。

工作流	用途
workflows/code-review/workflow.md	审查代码质量
workflows/pr-review/workflow.md	审查拉取请求
workflows/refactoring/workflow.md	使用测试进行安全重构（步骤 3 会检查全部十二种异味；步骤 5-8 会循环执行）
workflows/tdd.md	测试驱动开发周期
workflows/new-feature.md	构建新功能
workflows/bug-fix.md	妥善修复缺陷
workflows/test-strategy.md	规划测试覆盖范围
workflows/estimation.md	估算任务（PERT）
workflows/deadline-negotiation.md	应对不切实际的截止日期

参考资料

references/<topic>/ 包含 rules.md（规则）、examples.md（精选的 TypeScript 错误/正确示例对 — 优先使用这些示例，而不要自行编造）和 knowledge.md（概念）。

代码质量：命名 · 函数 · 类 · 注释 · 错误处理 · 单元测试 · 格式规范 · 代码异味

专业实践：专业素养 · 拒绝 · 承诺 · 编码实践 · TDD · 练习 · 验收测试 · 测试策略 · 时间管理 · 估算 · 压力 · 协作

提供相关建议前，先加载该主题的 rules.md，并注明所应用的规则 — 指明规则描述的设计问题，而非指出该问题的指标。若参考资料与通用知识相矛盾，以参考资料为准：它包含此技能针对 TypeScript 调整的内容和阈值。

guidelines.md 将症状映射到参考文件，并将任务映射到工作流。