#0 关于这个专栏 & 如何写好业务型代码注释

July 19, 2022

你好，我是回忆。受到一些朋友的启发，也想着开个专栏分享一些关于编程和生活的琐碎思考。这个专栏至少双周更新一次，不排除偶尔灵感比较密集的时候会不定期加更。每篇文章大概不会很长，感谢有缘相遇。

什么样的注释是好的业务代码注释？

很多文章都会讨论注释的有效性，并且会列举一些 good case 与 bad case。典型的 bad case 可能像这样：

// 组装列
function composeColumns() {
// 此处有一些逻辑
}

由于很多文章反复强调了这个问题，所以在真实代码中，其实很少看到上面这样的注释了（当然其实还是会有）。但是更多的时候，还有一种比较典型的 bad case：

// 组装列，需要根据 options 决定列的顺序
function composeColumns(options) {
  // 如果今天的气温大于 35 摄氏度，需要把水果放在第一列
  if (options.temperature > 35) {
  }

  // 如果今天的天空是蓝色的，那么需要把汽车放在第一列
  if (options.skyColor === 'blue') {
  }
}

上面这段代码可能出现在某个业务表格组件中，用来描述一段组装表格列时需要注意的表格顺序的逻辑。这种注释有一个特点是，写注释的人可能看一眼就能记起来（当然也可能记不起来）：「这是之前一个 xxxx 需求里，提到了这个组件可能会支持 xxxx 场景，所以需要在这里增加这个逻辑」；但是看这个注释的其他人就摸不着头脑，甚至心里暗骂：TMD温度和水果有什么关系？天空的颜色和TM汽车又有什么关系？

这里我们暂时不去讨论是否在设计上是否有更好的方式（比如它似乎违背了单一职责原则等），只从这个注释的有效性出发去看这个问题。当你看到这样一串注释，并且下一步需要修改里面的逻辑时，你的脑海里也许会思考一个问题：除了天空的颜色和温度还会不会有其他的情况需要注意？它还有没有什么其他的坑？这里这两个分支条件为什么没有 else？

那么，一个比较好的注释是什么样的呢？

// 组装列，需要根据 options 决定列的顺序
// 作者一: 在 20200718 迭代需求 xxxx 的 story1 里，规定了表格中温度阈值与表格列顺序的关系
// 其中提到，当天温度大于 35 度时，需要将水果放在第一列，其他与温度相关的情况暂时不考虑
// 作者二: 在 20211224 迭代需求 xxxx 的 story2 里，规定了表格中空气质量与表格列顺序的关系
// 其中提到，当天空气质量较好时，需要将汽车通行量放在第一列辅助判断模型有效性。
// 当规则冲突时，水果规则优先
function composeColumns() {
// 一些实现代码
}

关键在于，业务代码注释需要仔细描述某个代码分支与业务之间的关系，或者某个代码设计是如何从业务规则中抽象出来。不仅仅要概括性的描述 what，还要把 why 以及 how 这些隐藏在代码背后的产品决策与功能抽象详细地出来。