第 18 章：代码应显而易见
系列：软件设计的哲学 · 第 18/22 章
全书导读：00-overview.md
一句话总结
显而易见的代码让读者以最小脑力即可确认「在做什么、为何安全」——这是深模块在调用方的兑现：接口简单且用法一目了然。
核心观点浓缩
- 显而易见 ≠ 浅薄：深模块内部可以复杂，但典型用法路径应对读者透明
- 红旗信号：需要反复读才能懂、同样逻辑多种写法、关键假设无注释无命名支撑
- 手段组合：一致（第 17 章）、好命名（第 14 章）、注释补非显然处（第 13 章）、下拉复杂度（第 8 章）
- 重要代码应更显而易见——核心路径、错误恢复、并发边界，宁可冗长勿晦涩
- 工具辅助：静态分析、clang-tidy 规则可把「非显然模式」标红，但无法替代设计
- 读代码者视角：六个月后回来的你自己是首要读者
- 对称结构（成功/失败路径同形）是 obvious 的廉价技巧，值得默认采用
关键概念 / 金句
| 显而易见 | 非显而易见 |
|---|---|
| 调用顺序与生命周期在类型/接口中体现 | 文档外「必须先 A 后 B」 |
| 错误分支对称、可扫读 | 深层嵌套 + 早 return 混乱 |
| 魔法数有命名常量 | 字面量 0x1f3 散落 |
「若你需要运行代码才能理解代码，设计就还没到位。」
本章在全书中的位置
第 18 章为可读性篇（第 12–18 章）压轴，把注释、命名、一致性汇成读者体验标准。下一章起转入方法论批判（第 19 章），提醒 obvious 不能靠流程仪式替代，而靠设计本身。Obvious 是深模块的兑现测试：若接口简单但用法仍费解，说明抽象尚未完成。
个人思考与启发
连接诊断模块初版用嵌套 lambda 链处理超时重试，自己两周后也难改。改为线性 enum Step + 表驱动后，行数略增，但单步状态一眼可见，线上问题定位从小时级降到分钟级。Obvious 化往往意味着牺牲一点 DRY换可读——在关键路径上这是划算交易。On-call 工程师会感谢你在事故凌晨留下的线性控制流。
与《程序员修炼之道》对照
- 可逆性要求代码意图清晰，便于回滚与替换
- 「不写让读的人猜的代码」与 obvious 同义；本书更强调与模块深度的平衡
- 重构清单：若段代码需配口头讲解才懂，优先 obvious 化再谈性能
重点与注意
重点：Code Review 问「第一次读能否在 30 秒内把握意图？」
重点：obvious 化常通过重命名与提取函数完成，不必大拆架构。
注意：勿把「显而易见」当作拒绝抽象——重复十遍的展开比一次深模块调用更糟。
注意：性能热点（第 20 章）可局部不 obvious，但须注释 + 基准标明原因。
注意：Generated/boilerplate 代码 exempt 有限——仍须保证生成源模板 obvious。
注意：复杂 lambda 链若超三行嵌套，默认提取具名函数，除非 profile 证明热点。
导航：第 17 章 一致性 · 下一篇：第 19 章 软件潮流