5.1 编码规范与可维护代码

可维护代码，是未来的人能够安全理解和修改的代码。未来的人包括你的队友、接替你的人，以及三个月后已经做了很多其他事情的你。

编码规范不是为了让所有人变得一模一样。它减少无意义决策成本，让团队把注意力花在设计和行为上。

规范应该覆盖什么

有用规范是具体的：

• 领域概念命名约定。
• 文件和模块组织。
• 错误处理和日志期望。
• 验证边界。
• 测试期望。
• 公共 API 和意外决策的文档规则。
• 由工具自动执行的格式化和 lint。

避免需要无休止主观争论的规范。如果工具能执行，就让工具处理无聊工作。

可维护性信号

观察：

• 函数有一个清晰目的。
• 名字暴露领域含义。
• 公共接口小。
• 局部推理：理解一个变化不需要把整个系统装进脑子。
• 测试靠近被保护的行为。
• 注释解释 why，而不是复述代码已经说明的 what。

代码中的文档

好文档不是注释墙。它回答维护者自然会问的问题：

• 为什么这里有这条规则？
• 哪个外部约束迫使它长成这样？
• 什么不应该随便改？
• 哪次事故或决策导致了这个行为？

在未来困惑代价很高的地方写注释。