代码洁癖系列（四）：可忽略的注释

刚开始学编程的时候，老师就告诉我们，注释很重要，但是一直到现在，也没有人真正告诉过我要怎么写注释。还有很多人甚至干脆不写注释。所以今天想聊一下到底如何写注释。

提到注释就让我想起一个段子：两个程序员去饭店吃饭，点菜的时候程序员甲说：我要吃宫保鸡丁，程序员乙就帮他记。

宫保鸡丁

然后程序员甲又说：我不想吃宫保鸡丁了，换成地三鲜吧。程序员乙就说好的，然后又帮他记上了。

1 2	//宫保鸡丁地三鲜

这个段子也从侧面反映了程序员们习惯性忽略注释的事实。段子讲完了，下面插播一些正文。

注释不能拯救糟糕的代码

首先，我想说的可能和大多数人的观点相左：尽量少用注释！没错，尽量少用。因为注释是会骗人的，而且时间越长的注释越容易骗人，因为大部分人在修改代码的时候都不会去修改注释。少写注释，尽量用代码去描述你要做什么。当你要写注释的时候，就要思考一下，别人为什么不能通过代码理解你想表达什么。这时你需要尝试修改代码，来达到上述目的。

1
2
3

// Check to see if the employee is eligible for full benefits
if (employee.flags & HOURLY_FLAG) &&
    (employee.age > 65)

看一下这段代码，如果只看代码，可以理解它要表达什么吗？

1	if (employee.isEligibleForFUllBenefits())

花上点时间，把代码改成这样，是不是不用注释也可以读懂了？

我们这里说尽量少使用注释，并不是完全不用注释，在某些情况下，我们需要注释。那么什么样的注释才算是好的注释呢？

法律信息

有时，公司代码规范会要求注明版权和著作权。那么我们就应该将这些信息放到源文件的开头位置。

提供信息的注释

1 2	// Returns an instance of the Responder being tested. protected abstract Responder responderInstance()

这样的注释就是不错的注释，给读者提供了返回值的信息，不过，如果我们把函数命名为responderBeingTested，那么这个注释也就显得多余了。

阐释

可以用注释把某些难以理解的参数或返回值翻译成可以理解的形式。当前，前提是如果这些代码你无法修改，比如参数或返回值是标准库的一部分。这时阐释就显得很有用。举过来一个栗子。

1
2
3

assertTrue(a.compareTo(a) == 0);  // a == a
assertTrue(a.compareTo(b) != 0);  // a != b
assertTrue(a.compareTo(b) == -1); // a < b

不过这样的阐释也有缺点，那就是它有可能是不正确的，我们需要小心确认其正确性。如果缺失正确性，那么这样的阐释只会起到负面作用。

TODO注释

TODO注释是比较常用的注释，可以在代码里添加工作列表，例如，对一个空实现函数添加TODO注释，就可以解释这里为什么是空实现，以及以后要实现什么。

公共API的Javadoc

这个也许最令人欣赏的注释习惯了。不过目前我们通常用swagger来代替注释。对swagger感兴趣的童鞋可以戳这里。

所谓见贤思齐焉，见不贤而内自省也。看完了好的注释，就要想想怎么才能写出好的注释；接下来再来看看坏的注释，看的同时需要多反省自己，尽量避免写出坏的注释。

自说自话

写的东西只有自己能看懂，别人都不明白要表达什么。如果读代码时连注释都看不明白，还有人想看下去吗。

日志式注释

几乎把代码的每次修改记录都写到注释里，也许在那个没有代码版本控制工具的远古时代，这么做还有一定的意义。但是现在我们拥有很多健壮的代码版本控制工具，这样的注释也就变得毫无意义。

在代码里加上自己的签名也是一样的道理，我们都可以通过代码版本控制工具查看具体的创建者和修改者，而不是只记住创建者。

注释掉代码也是一样，我们用版本控制工具可以轻松找回以前的代码，不需要的代码可以直接删掉，而不是留一个注释掉的代码放在那里。

废话注释

1 2	/** The day of the month. */ private int dayOfMonth;

我不想多废话了……

结语

也许文中的观点和大多数人的思维相左，可能我的有些观点是错的，欢迎大家关注我的微信公众号，和我讨论注释究竟是否必要。