[译] 关注代码健康:要不要写注释?

2020-07-22 · 技术 · 约 5 分钟读完

译注:这是一篇 Google 的小品文,主要讨论了代码注释何时写、如何写。文章虽短,却直击要害。Google 功力可见一斑。

原文: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()) { ... }