# 可读代码与渐进式整理

适用范围：编写、审查或小范围整理实现代码时，用本文降低读者理解行为、数据流和副作用的成本。先遵循目标项目的语言规范、自动格式化规则和已有可靠约定；整理代码默认保持输出、异常、持久化、调用次数与时序不变。模块或 API 边界的重大调整见[软件设计哲学](software-design-philosophy.md)。

## 让代码按意图顺序阅读

- 先确认方法对外承诺什么，再安排内部步骤。常见顺序是拒绝无效输入、读取依赖数据、计算结果、修改状态、调用外部系统、返回结果；真实业务顺序优先于这份列表。
- 相邻语句能用同一个短动作概括，就放在同一段；意图或副作用类别改变时，用一个空行分段。不要逐句空行，也不要拆开必须一起理解的计算、状态变更或 `if/else`。
- 正常路径尽量直接可见。前置失败可用卫语句处理；若多个条件共同构成一个决策，则保留在一起，不机械增加提前返回。
- 变量靠近第一次使用处，名称表达业务含义、单位与状态；密集条件可用有意义的名字说明。查询、写入、网络调用等副作用应从方法名或契约中可见。
- 不为了少几行而压缩分支、复用不同含义的变量，或把一次调用的状态藏进服务实例字段。

空行和命名先表达结构。面向中文读者的多阶段业务方法，如果仅靠英文标识符仍难以辨认阶段，可在有业务含义的段落前加一行中文意图说明；简单赋值和返回无需逐段注释。注释应遵循[有用的代码注释](useful-code-comments.md)，不能替代清晰的代码。

## 判断要不要提取

提取方法、类或服务应有实际收益：隐藏调用者不需要知道的细节，集中一个不变量，形成稳定概念，或隔离确实独立变化的知识。提取也增加名称、接口、参数、错误语义和阅读跳转；如果读者仍必须同时打开调用方和新助手才能理解一个概念，就先保持局部。

相似代码未必是同一知识。两段逻辑若为不同业务原因而变化，可以继续分开；共享抽象开始堆积模式参数和布尔开关时，检查是否应恢复独立路径，再从当前需求识别共性。不要用固定行数、方法数、嵌套层数或注释数量裁定质量。

## 做一次有边界的整理

1. 查看改动范围、相关调用方、已有行为约定和当前差异，只处理此次任务涉及的代码；保留他人的未提交工作。
2. 优先删去确定无用的局部代码，修正误导名称，显式化隐藏状态与副作用，再整理控制流和代码段落。只在边界确有收益时提取。
3. 将格式化交给项目工具。不要把全文件格式化、无关重构或大规模重写混入行为修改。
4. 复读差异，核对输出、异常、状态变化、外部调用及其顺序。按项目已有方式做与改动相关的验证，明确哪些方面尚未验证。

难读的遗留代码可能包含尚未恢复的业务约束和历史修复；先查清再小步整理。行为需要改变时，应把行为修改与纯整理区分清楚，不把“简化”当作改变契约的理由。

## 参考

- [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html)：局部变量靠近首次使用、空行可组织逻辑小节；具体格式以目标语言和项目约定为准。
- [Google Engineering Practices：代码审查关注点](https://google.github.io/eng-practices/review/reviewer/looking-for.html)：审查复杂度、命名、注释与一致性，避免把个人风格当作阻塞性问题。
- [Anthropic code-simplifier](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier)：在保持行为的前提下整理近期改动；本文只提炼适用于一般项目的做法。