要不要写代码注释 #

这是一篇人家从 google test blog 翻译过来的文章，2017 年发表的，对要不要写注释的问题直击关键，所以想要对文章加入一些自己的理解，再记录一遍。

在阅读代码时，没有什么东西比一条恰到好处的注释更有帮助。但要注意，注释并非越多越好。有时，一段需要注释的代码，意味着一段需要重构的代码。

只在代码无法自我描述时才添加注释 #

如果你觉得代码逻辑要用注释才能讲清楚，可能你的代码无法自我描述，不妨先做以下尝试：

• 使用带说明性质的中间变量

原代码：

// 减去商品的折扣
finalPrice = numItems * itemPrice - min(5, numItems) * itemPrice * 0.1

重构后：

price = numItems * itemPrice
discount = min(5, numItems) * itemPrice * 0.1
finalPrice = price - discount

• 提取方法

原代码：

// 过滤敏感词
for (String word: words) {
  ...
}

重构后:

filterOffSensitiveWords(words) // off 表明是删除 而不是拾取

• 使用更加具体的变量

原代码：

int width = ...; // 宽度（单位：px）

重构后：

int widthInPixels = ...;

• 如果代码中假定了某种情况，则为其添加判断语句

原代码

// height 永远大于 0，因此可直接作为除数
return width / height

重构后：

checkArgument(height > 0)
return width / height

总结

把注释的意图包含到代码从，从而消除不必要的注释。

以下情况适合添加注释 #

• 解释代码意图：为何这么做？（不要解释代码做了什么）

// 因为开销过大，只计算一次

• 避免他人过于负责，顺手“修复”你的“bug”

// 创建一个新的 Foo 实例，因为它不是线程安全的

已知的可能存在问题的代码，使用注释说明为何留下这个问题

• 澄清：可能让他人产生疑问的代码

// 必须要注意顺序，因为…

• 解释你为何写了一段看着很糟糕的代码

@SuppressWarnings("unchecked") // 无需检查安全性，因为…

往往很多时候，并不能意识到写了很糟糕的代码，否则极可能不会出现糟糕的代码。所以，通常，只有意识到这段代码有更好的方案，依然保留看着很糟糕的代码时，才可能写注释。

其他情况，避免写一些仅仅重申代码在干什么的注释 #

这些代码只会干扰阅读：

// 获取所有用户
useService.getAllUsers()

// 检测 name 是否为空
if (name.isEmpty()) {
  // ...
}

对非英语为母语的开发者，让他们准确的使用英语表达代码意图并非易事（我看过不少使用拼音缩写命名变量的开发者），所以对使用了不正确的英文单词、拼音缩写，然后进行注释，是有必要的。

当然，最好是避免随意使用缩写，制造新的英文单词，尤其是拼音缩写，比如 危险区 ， wxq 不如 weiXianQu ，不如 dangerousArea

参考 #

[译] 关注代码健康：要不要写注释？