simplify

代码简化

概述

通过降低复杂度来简化代码，同时保持行为完全一致。目标不是减少代码行数，而是让代码更易于阅读、理解、修改和调试。每次简化都必须通过一个简单的检验：“新团队成员能否比理解原代码更快地理解它？”

适用场景

• 功能已正常运行且测试通过，但实现显得过于繁重
• 代码审查指出了可读性或复杂度问题
• 遇到深层嵌套逻辑、冗长函数或含义不清的名称
• 重构在时间压力下编写的代码
• 整合散落在多个文件中的相关逻辑
• 合并带来了重复或不一致的更改之后

不适用场景：

• 代码已经简洁易读——不要为了简化而简化
• 你还不理解代码的作用——先理解，再简化
• 代码对性能至关重要，而“更简单”的版本会明显变慢
• 你即将彻底重写整个模块——简化很快就会被丢弃的代码是在浪费精力

五项原则

1. 精确保留行为

不要改变代码的行为，只改变表达方式。所有输入、输出、副作用、错误行为和边界情况都必须保持一致。如果你不确定某项简化能否保留行为，就不要进行。

每次更改前，都要问自己：

• 对每种输入，这是否会产生相同的输出？
• 这是否会保持相同的错误行为？
• 这是否会保留相同的副作用和执行顺序？
• 采用什么与改动相称的最终状态验证，才能发现行为变化？

2. 遵循项目惯例

简化意味着让代码更符合代码库的惯例，而不是强加外部偏好。

开始简化前：

1. 阅读 AGENTS.md / 项目惯例
2. 研究相邻代码如何处理类似模式
3. 遵循项目在导入、命名、函数风格、错误处理和类型注解方面的风格

破坏项目一致性的简化不是简化，而是在制造无谓改动。

3. 清晰优先于巧妙

如果紧凑的代码需要停下来琢磨才能看懂，那么明确的代码更好。

• 将嵌套三元表达式替换为清晰的控制流
• 将密集的内联转换替换为具名的中间步骤，前提是这样能让意图更清楚
• 保留有助于理解的名称，即使会多写几行

4. 保持平衡

谨防过度简化：

• 不要内联掉承载语义的名称
• 不要把无关逻辑合并到一个更大的函数中
• 不要移除有助于可测试性或可扩展性的抽象
• 不要为了减少行数而牺牲易懂性

5. 聚焦于已更改的部分

默认只简化近期修改过的代码。除非有人明确要求，否则避免顺手重构无关代码。

流程

第 1 步：动手前先理解

更改或移除任何内容之前，先弄清楚它存在的原因。

回答以下问题：

• 这段代码负责什么？
• 谁会调用它？它会调用什么？
• 有哪些边界情况和错误路径？
• 是否有测试定义了预期行为？
• 它为什么会采用这种写法？

如果无法回答这些问题，请先阅读更多上下文。

第 2 步：寻找简化机会

可关注以下迹象：

• 嵌套层级过深
• 函数过长且职责混杂
• 嵌套三元表达式
• 布尔标志参数
• 重复的条件判断
• 通用或容易误导的名称
• 重复逻辑
• 死代码
• 没有带来价值的包装器或抽象

第 3 步：逐步应用更改

每次只做一项简化。

每项简化都要：

1. 进行更改
2. 使用与改动相称的最终状态验证计划，检查行为是否得以保留
3. 只有在证据支持行为得以保留时，才保留这项更改

尽可能将重构与功能开发分开。

步骤 4：验证结果

简化后，请确认：

• 代码确实更易于理解
• 差异清晰且易于审查
• 仍符合项目约定
• 行为、错误处理或副作用均未改变

本仓库指南

• 优先使用直观的 TypeScript，而非巧妙的精简写法
• 保留现有运行时行为、测试和钩子
• 如果明确的命名和更小、更专注的辅助函数有助于提升可读性，则优先采用
• 将重构严格限制在任务或审查反馈的范围内

最终状态验证

针对最终差异，制定适度的最终状态验证计划。运行仓库和发布说明要求的检查；仅当变更范围或明确提出的不确定性有此需要时，才补充或重复验证证据。