代码的坏味道（13）——过多的注释(Comments)

坏味道——过多的注释(Comments)

特征

注释本身并不是坏事。但是常常有这样的情况：一段代码中出现长长的注释，而它之所以存在，是因为代码很糟糕。

问题原因

注释的作者意识到自己的代码不直观或不明显，所以想使用注释来说明自己的意图。这种情况下，注释就像是烂代码的除臭剂。

最好的注释是为函数或类起一个恰当的名字。

如果你觉得一个代码片段没有注释就无法理解，请先尝试重构，试着让所有注释都变得多余。

解决方法

如果一个注释是为了解释一个复杂的表达式，可以运用 提炼变量(Extract Variable) 将表达式切分为易理解的子表达式。
如果你需要通过注释来解释一段代码做了什么，请试试 提炼函数(Extract Method) 。
如果函数已经被提炼，但仍需要注释函数做了什么，试试运用 函数改名(Rename Method) 来为函数起一个可以自解释的名字。
如果需要对系统某状态进行断言，请运用 引入断言(Introduce Assertion) 。

收益

代码变得更直观和明显。

何时忽略

注释有时候很有用：

当解释为什么某事物要以特殊方式实现时。
当解释某种复杂算法时。
当你实在不知可以做些什么时。

重构方法说明

提炼变量(Extract Variable)

问题

你有个难以理解的表达式。

void renderBanner() {
  if ((platform.toUpperCase().indexOf("MAC") > -1) &&
       (browser.toUpperCase().indexOf("IE") > -1) &&
        wasInitialized() && resize > 0 )
  {
    // do something
  }
}

解决

将表达式的结果或它的子表达式的结果用不言自明的变量来替代。

void renderBanner() {
  final boolean isMacOs = platform.toUpperCase().indexOf("MAC") > -1;
  final boolean isIE = browser.toUpperCase().indexOf("IE") > -1;
  final boolean wasResized = resize > 0;

  if (isMacOs && isIE && wasInitialized() && wasResized) {
    // do something
  }
}

提炼函数(Extract Method)

问题

你有一段代码可以组织在一起。

void printOwing() {
  printBanner();

  //print details
  System.out.println("name: " + name);
  System.out.println("amount: " + getOutstanding());
}

解决

移动这段代码到一个新的函数中，使用函数的调用来替代老代码。

void printOwing() {
  printBanner();
  printDetails(getOutstanding());
}

void printDetails(double outstanding) {
  System.out.println("name: " + name);
  System.out.println("amount: " + outstanding);
}

函数改名(Rename Method)

问题

函数的名称未能恰当的揭示函数的用途。

class Person {
  public String getsnm();
}

解决

修改函数名。

class Person {
  public String getSecondName();
}

引入断言(Introduce Assertion)

问题

某一段代码需要对程序状态做出某种假设。

double getExpenseLimit() {
  // should have either expense limit or a primary project
  return (expenseLimit != NULL_EXPENSE) ?
    expenseLimit:
    primaryProject.getMemberExpenseLimit();
}

解决

以断言明确表现这种假设。

double getExpenseLimit() {
  Assert.isTrue(expenseLimit != NULL_EXPENSE || primaryProject != null);

  return (expenseLimit != NULL_EXPENSE) ?
    expenseLimit:
    primaryProject.getMemberExpenseLimit();
}

注：请不要滥用断言。不要使用它来检查”应该为真“的条件，只能使用它来检查“一定必须为真”的条件。实际上，断言更多是用于自我检测代码的一种手段。在产品真正交付时，往往都会消除所有断言。

后记

一些朋友对我这篇文字有很多质疑。
在这里，我想集中再强调一下我的观点，避免让大家有歧义。
注释的作用，很多时候，非常类似于马路上的警示牌：“前方有坑，悠着点！”难道因为有了警示牌，就不用把坑给填上了吗？但是，在坑没有填上之前，把警示牌给撤了或者压根就没想要立个警示牌，这就更加不应该了。
不知我这么说，大家是否更容易理解。

引申阅读

欢迎继续阅读 代码的症与药 系列文章。