代码健康(7):注释并不总是好事儿

乔梁 | 2021-03-07

要写注释,还是不用呢?

当阅读代码时, 没有什么比良好的注释内容更给力的了。

然而, 注释并不总是好事儿。

在哪些情况下,不应该写注释,而是应该重构

假如你的代码意图无法做到“不言自明”,再使用注释也不迟。

如果你认为需要用注释来解释一段代码在做什么,那么,还是先试一试下面的方法吧:

  • 引入一个解释性的变量。

将下面这段代码

        // Subtract discount from price.
        finalPrice = (numItems * itemPrice)
                      - min(5, numItems)
                      * itemPrice * 0.1;

改写为

        price = numItems * itemPrice;
        discount = min(5, numItems) * itemPrice * 0.1;
        finalPrice = price - discount;
  • 抽取出一个新的方法( methed )。

例如,将下面的这段代码

  // Filter offensive words.
  for (String word : words) {
    ...
    ...
  }

改写为:

  filterOffensiveWords(words);
  • 使用一个更有描述性的命名。

例如,将下面的这段代码

  // Width in pixels.
  int width = ...;

改写为:

int widthInPixels = ...;
  • 万一你的代码有假设条件,就要增加一个检查点,而不是注释。

例如,

  // Safe since height is always > 0.
  return width / height;

改写为:

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

在哪些情况下,应该写注释

  • 展示你的意图:解释为什么写这段代码,而不是它在做什么。

    // Compute once because it’s expensive.

  • 保护未来那个善意的想修改你代码的人,以免它错误地“修复”了你的代码。

    // Create a new Foo instance because Foo is not thread-safe.

  • 声明式:代码审查期间出现的问题或代码的读者可能有的问题。

    // Note that order matters because…

  • 如果看起来你写了一段违反软件工程实践的糟糕代码,那就解释一下你的理由。

    @SuppressWarnings("unchecked") // The cast is safe because…

避免注释仅仅是重复了代码已表达的内容。

因为这种做法是令人反感的,例如下面两段代码所示:

  // Get all users.<br/>
  userService.getAllUsers();
  // Check if the name is empty.
  if (name.isEmpty()) { ... }