5.1 一致性：比局部最优更重要

5.1 一致性：比局部最优更重要

本节摘要：一致性要求整个代码库对同类问题采用同类解法，读起来像出自一人之手。本节定义一致性的六个层面（格式、命名、结构、逻辑、注释、接口），论证"统一的普通方案胜过各自精彩的最优方案"，给出规范文档、自动化工具、代码评审三件套的维护机制，并讨论允许合理偏离的例外管理。

上手前先明确

阅读完本节，你应当能够：

1. 说出一致性的六个层面并各举一个不一致的例子
2. 解释"一致性压倒局部偏好"的经济学理由
3. 设计规范、工具、评审三位一体的一致性维护机制
4. 管理合理偏离：何时允许例外、如何记录例外
5. 识别并阻止破窗效应在代码库中的蔓延

一、问题与直觉：一个项目三种异步

一个前端项目里，处理异步操作竟有三种写法并存：老代码用回调函数，中期代码用 Promise 链式调用，新代码用同步风格的等待语法。三种写法都对，各自在写成的年代也都是最佳实践——问题在于并存。新人接手时要在同一个文件里切换三种思维模式；出问题时排查者要先识别"这是哪一派的代码"再套用对应的排查套路；最伤的是想统一时发现三种写法的错误处理路径完全不同，迁移成本高到没人敢立项。

这个案例揭示了不一致的真正代价：它不是审美问题，是认知切换税。心理学上叫"任务切换损耗"——每次在两套模式间切换，注意力都要付出一次额外的进入成本。代码库里每多一种"方言"，全团队每天都要交无数次切换税。这也解释了一条反直觉的结论：统一的普通方案胜过各自精彩的最优方案。A 用法在 A 场景比 B 好百分之十，B 用法在 B 场景比 A 好百分之十，但混用让所有场景都付出认知税——净收益为负。一致性的价值不是让每个局部最优，而是让整体最优。

另一个维度是信任与预期。一致的代码库里，读者可以安全地预测："这个项目处理错误一定是那套模式，找日志一定在那个位置。"预测成立，阅读就快；预测失效（这次居然不一样），就要重新建立心智模型。一致性本质上是在全团队积累"可复用的阅读预期"。

二、核心原理：六个层面与维护机制

2.1 一致性的六个层面

• 格式一致：缩进、空格、换行、括号位置全库统一（第 2.3 节，工具全自动）。
• 命名一致：同类实体同种风格，布尔都带 is/has 前缀，函数都按动词词汇表命名（第 2.2 节）。
• 结构一致：目录组织方式、文件命名、模块内代码顺序统一；所有控制器住在按功能划分的同类目录里（第 3.2 节）。
• 逻辑一致：同类技术问题用同一套模式解——错误处理统一走异常，日期格式化统一调同一个工具函数，异步统一用一种写法。
• 注释一致：文档注释的标签与详略程度统一，TODO 的三要素格式统一（第 3.1 节）。
• 接口一致：对外 API 的命名、参数顺序、返回值结构、错误码体系统一；调用方学一次就能举一反三。

注意六个层面的一致性难度递增：格式与命名可以全自动化，结构与逻辑靠规范加评审，注释与接口的一致性完全依赖团队的自觉与评审把关——这也是为什么一致性需要"三件套"而不是单靠工具。

2.2 三件套维护机制

规范文档定标准：一致性不能靠口口相传，必须文档化且可访问。文档的关键品质是具体可判定——"缩进四格"是规则，"适当缩进"是愿望；每条规则配正反示例，判定标准客观，评审才不打架。

自动化工具打底：格式化工具消灭格式分歧（零人工），Linter 把命名风格、禁用模式变成机器规则（详见第 6 章）。原则是机器能管的不占用人的注意力——评审时间留给逻辑与设计。

代码评审把关：机器管不了的层面（结构、逻辑、注释、接口一致性）靠评审守住。评审清单里放一致性检查项；发现的一致性问题若规范没覆盖，反过来补充规范——评审是规范的雷达。

一致性的六个层面与守卫方式

三、工程实践要点

3.1 例外的管理

一致性不等于僵化。确实存在合理偏离：性能关键路径上的特殊写法、第三方约束导致的无奈选择。规范不应该是"绝不"，而应该是"偏离必须显式"——写清偏离的原因、适用范围，最好在代码处以注释标记，让读者知道"这是深思熟虑的例外，不是漏网之鱼"。未记录的偏离会被后来者当成"原来可以这样写"的先例，一致性从此漏水。

3.2 破窗效应的防守

第 1.2 节讲过破窗效应，这里给出防守操作。第一道防线是增量严守：新代码与被修改的代码必须合规，存量放行（第 1.3 节的渐进策略）。第二道防线是工具全覆盖：CI 检查所有新提交，绕过编辑器直接改文件的人也会被流水线拦下。第三道防线是评审不妥协：对不合规的提交，评审意见是"先合规再评审逻辑"，而不是"这次算了下次注意"——"下次注意"就是第一块破窗。

3.3 存量不一致的收敛

老项目的三种异步并存怎么办？答案不是一次性大迁移（风险与工时都不可行），而是定方向、划增量、给工具：规范定死目标写法；所有新代码用目标写法，修改旧代码时顺手迁移 touched 的部分；提供自动化迁移工具或脚本（多数场景有现成的语法转换工具）降低迁移成本；用 Linter 规则只对目标写法的目录生效，渐进扩大覆盖。收敛以季度为周期度量，不求速胜。

⚠️ 常见坑：把一致性当成拒绝一切改进的挡箭牌。"我们一直这么写"不是理由——如果新方案客观更优（更安全、更简洁），正确路径是全库统一升级而不是拒收。一致性的对象是"当下最优解的全库统一"，不是"历史解的永久冻结"。

💡 关键直觉：评估一个方案时，把它乘以"出现的次数"再算成本。一个局部小瑕疵重复两百次就是大问题；一个稍笨但统一的模式，摊到全库反而总成本最低。

核心回顾

• 认知切换税：多种"方言"并存的代价不是审美而是注意力，混用让局部最优变成整体次优
• 统一压倒偏好：统一的普通方案胜过各自精彩的最优方案
• 六个层面：格式、命名、结构、逻辑、注释、接口，越往下越可自动化
• 三件套：规范定标准、工具打底、评审把关，评审同时是规范的雷达
• 例外要显式：合理偏离必须记录原因与范围，未记录的偏离是漏水起点
• 破窗三防线：增量严守、工具全覆盖、评审不妥协
• 一致性不是冻结：更优方案出现时走全库统一升级，而非拒收

下一节把时间轴拉长：可维护性——一张贯穿软件生命周期的成本账。