Zc Code Simplification

Code Simplification

角色定位

在不改变行为的前提下降低代码理解成本。目标不是减少行数，而是让下一位维护者更快理解、更安全修改、更容易验证。

何时使用

• 功能已经工作且测试通过，但实现明显偏重。
• review 指出可读性、重复、嵌套或抽象层级问题。
• 最近修改的代码引入了重复或不一致。
• 需要在进入下一轮功能前降低维护成本。

不适用：

• 还没有理解代码为什么存在。
• 缺少能保护行为的测试或验证方式。
• 性能关键路径会因为“更简单”变慢。
• 即将废弃或重写的代码。

快速路径

1. 明确要保持不变的行为、输入、输出、副作用和错误路径。
2. 读取邻近代码和项目约定，确认本仓库的风格。
3. 找一个具体简化目标：命名、重复、嵌套、函数职责、死代码、无效抽象。
4. 一次只做一个简化切片。
5. 每个切片后运行最小相关测试。
6. 对比前后可读性和 diff 可审性。
7. 如果新版本更难审或行为证据不足，回退该切片。

简化信号

优先处理具体信号，而不是泛泛“感觉复杂”：

• 3 层以上嵌套，可以改为 guard clause 或提取谓词。
• 长函数承担多个职责，可以拆成命名清楚的小函数。
• 重复条件或重复逻辑，可以提取共享函数。
• 命名不能表达业务含义，可以重命名。
• 注释解释“做什么”，代码本身可表达时可以删除；解释“为什么”的注释保留。
• 只有一个实现的过度抽象，可以考虑内联。
• 手写逻辑重复仓库已有 helper、标准库或平台原生能力，可以删除重复实现并复用现有 owner。
• 新依赖只服务少量可读代码，且没有带来明确的正确性、兼容性或维护收益，可以移除依赖并使用更直接的实现。
• 配置、接口、factory 或 adapter 只有一个当前消费者，且不存在真实边界契约，可以内联；不能只凭实现数量删除必要的外部系统隔离。
• 不可达分支、未使用变量、过期注释，可以在确认后删除。

行为保护

简化前先回答：

• 现有测试覆盖了什么？
• 哪些边界没有测试但需要人工验证？
• 这个代码是否有历史原因、平台限制或性能约束？
• 是否有调用方依赖当前副作用或错误行为？

无法回答时，先回到 codebase-onboarding 或 test-driven-development 补证据。

反模式

• 为了少几行牺牲可读性。
• 把有意义的 helper 内联成重复逻辑。
• 顺手重构无关文件，制造 review 噪声。
• 同一个提交里混合功能变更和简化重构。
• 没有测试保护就改公共接口或错误路径。

输出契约

Simplification evidence:
- Target:
- Behavior preserved:
- Change made:
- Tests / verification:
- Before/after readability:
- Remaining risk:

推荐结论：

Recommendation: <apply / stop / add tests first / defer> because <行为证据、维护收益和被放弃替代方案>。

如果不能证明行为保持不变，默认不要简化。