代码洁癖系列(四):可忽略的注释

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

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

1
宫保鸡丁

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

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;

我不想多废话了……

结语

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

Jackey Wang wechat
欢迎关注我的公众号,一起讨论如何写bug
-------------本文结束感谢您的阅读-------------
原创不易,感谢支持