Markdown 原文

可读代码与渐进式整理

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

让代码按意图顺序阅读

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

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

判断要不要提取

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

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

做一次有边界的整理

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

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

参考

Google Java Style Guide：局部变量靠近首次使用、空行可组织逻辑小节；具体格式以目标语言和项目约定为准。
Google Engineering Practices：代码审查关注点：审查复杂度、命名、注释与一致性，避免把个人风格当作阻塞性问题。
Anthropic code-simplifier：在保持行为的前提下整理近期改动；本文只提炼适用于一般项目的做法。