第 17 章：一致性
系列：软件设计的哲学 · 第 17/22 章
全书导读：00-overview.md
一句话总结
一致性本身降低复杂度——同类事物用同一模式表达，读者只需学一次规则，即可在全库复用理解力。
核心观点浓缩
- 不一致迫使读者每次重新猜：错误处理方式、命名风格、目录结构、API 形状
- 一致性维度：命名（第 14 章）、错误/日志模式、层间调用方向、文件组织、注释格式
- 深模块与一致风格不矛盾：内部可复杂，对外形态应可预测
- 引入新风格须有全库迁移计划或明确「新代码从 X 起用 B」边界
- 文档化团队约定（短 ADR 或 CONTRIBUTING），比口头传统可靠
- 可机械检查的约定（lint、格式化）比「大家自觉」更一致——人脑不适合记百条风格
- 第三方库风格与项目不一致时，用薄适配层隔离，勿让两种风格在业务代码交织
关键概念 / 金句
| 一致 | 不一致的代价 |
|---|---|
全库 Result<T, Error> | 有的抛异常、有的返回码、有的 void+日志 |
插件均 register() 入口 | 各插件自定义静态初始化顺序 |
UI 异步统一 QFutureWatcher 模式 | 混用 callback、信号、轮询 |
「不一致是一种分布式复杂度——每个差异都是读者多记一条规则。」
本章在全书中的位置
第 17 章为可读性篇收束之一，与第 18 章「显而易见」相邻：一致让代码看起来应该的样子可预测。亦支撑第 7 章分层——层内一致、层间边界清晰，否则抽象泄漏。大型 C++/Qt 工程里，风格一致往往比个人偏好最优更能降低全库认知负荷。
个人思考与启发
JMSession 里曾混用 slotXxx 与 onXxx 作槽名，新人搜信号连接总漏一半。统一为 slot 前缀并 lint 新文件后，连接代码可读性提升，Review 焦点回到业务而非风格争论。错误处理也宜一致：要么全库抛 SessionError，要么统一 Result，混用会迫使读者每文件重新建立心智模型。 onboarding 文档只链到一份风格指南即可。Code Review checklist 加入「是否引入第二种错误处理风格」一条，成本低见效快。
与《程序员修炼之道》对照
- 纯文本的力量：约定应写下来并可机器检查（clang-format、自定义 lint）
- 「易于反转」不反对一致——在一致框架内保留替换实现的空间
- 正交性与一致性：模块正交 + 对外一致，是大型 C++/Qt 代码库可维护的双翼
重点与注意
重点：选 convention 时宁少勿多——三条严格执行好过十条半吊子。
重点：老代码不一致时，触须改须（boy scout rule），勿大爆炸重写。
注意：一致不等于统一滥用设计模式——模式应服务复杂度，非徽章收集。
注意：跨语言边界（C++ / Python 子进程）也应有协议层一致（JSON 字段、错误码）。
注意：引入新风格时旧风格文件可标注 deprecated pattern，引导渐进迁移。
注意：Qt.pro/CMake 目标名与 C++ 命名空间宜同根，减少跨层认知切换。
导航：第 16 章 修改既有代码 · 下一篇：第 18 章 代码应显而易见