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

原文：Code Health: To Comment or Not to Comment?

作者：Dori Reuveni, Kevin Bourrillion

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

只在你的代码无法解释自身时才添加注释。

如果你觉得代码逻辑要用注释才能讲清楚，不妨先做以下尝试：

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

  原代码：

  // 减去商品的折扣
  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) { ... }

  重构后：

  filterOffensiveWords(words);

• 使用一个更加具体的变量名

  原代码：

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

  重构后：

  int widthInPixels = ...;

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

  原代码：

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

  重构后：

  checkArgument(height > 0);
  return width / height;

以下这些情况适合添加注释

• 解释意图：这段代码为什么要这么做（而非这段代码做了什么）

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

• 避免接手代码的人过于负责，顺手「修」掉了你的「bug」

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

• 澄清：有些地方，读你代码的人可能会产生疑问

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

• 解释你为什么要写一段貌似很屎的代码

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

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

它们只会干扰阅读：

// 获取所有用户
userService.getAllUsers();

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