刚开始学编程的时候，老师就告诉咱们，注释很重要，可是一直到如今，也没有人真正告诉过我要怎么写注释。还有不少人甚至干脆不写注释。因此今天想聊一下到底如何写注释。java
提到注释就让我想起一个段子：两个程序员去饭店吃饭，点菜的时候程序员甲说：我要吃宫保鸡丁，程序员乙就帮他记。程序员
宫保鸡丁
而后程序员甲又说：我不想吃宫保鸡丁了，换成地三鲜吧。程序员乙就说好的，而后又帮他记上了。编程
//宫保鸡丁
地三鲜
这个段子也从侧面反映了程序员们习惯性忽略注释的事实。段子讲完了，下面插播一些正文。微信
注释不能拯救糟糕的代码编辑器
首先，我想说的可能和大多数人的观点相左：尽可能少用注释！没错，尽可能少用。由于注释是会骗人的，并且时间越长的注释越容易骗人，由于大部分人在修改代码的时候都不会去修改注释。少写注释，尽可能用代码去描述你要作什么。当你要写注释的时候，就要思考一下，别人为何不能经过代码理解你想表达什么。这时你须要尝试修改代码，来达到上述目的。函数
// Check to see if the employee is eligible for full benefits
if (employee.flags & HOURLY_FLAG) &&
(employee.age > 65)
看一下这段代码，若是只看代码，能够理解它要表达什么吗？工具
if (employee.isEligibleForFUllBenefits())
花上点时间，把代码改为这样，是否是不用注释也能够读懂了？flex
咱们这里说尽可能少使用注释，并非彻底不用注释，在某些状况下，咱们须要注释。那么什么样的注释才算是好的注释呢？spa
法律信息.net
有时，公司代码规范会要求注明版权和著做权。那么咱们就应该将这些信息放到源文件的开头位置。
提供信息的注释
// Returns an instance of the Responder being tested.
protected abstract Responder responderInstance()
这样的注释就是不错的注释，给读者提供了返回值的信息，不过，若是咱们把函数命名为responderBeingTested，那么这个注释也就显得多余了。
阐释
能够用注释把某些难以理解的参数或返回值翻译成可读的形式。当前，前提是若是这些代码你没法修改，好比参数或返回值是标准库的一部分。这时阐释就显得颇有用。举过来一个栗子。
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感兴趣的童鞋能够戳阅读原文。
所谓见贤思齐焉，见不贤而内自省也。看完了好的注释，就要想一想怎么才能写出好的注释；接下来再来看看坏的注释，看的同时须要多检讨本身，尽可能避免写出坏的注释。
自说自话
写的东西只有本身能看懂，别人都不明白要表达什么。若是读代码时连注释都看不明白，还有人想看下去吗。
日志式注释
几乎把代码的每次修改记录都写到注释里，也许在那个没有代码版本控制工具的远古时代，这么作还有必定的意义。可是如今咱们拥有不少健壮的代码版本控制工具，这样的注释也就变得毫无心义。
在代码里加上本身的签名也是同样的道理，咱们均可以经过代码版本控制工具查看具体的建立者和修改者，而不是只记住建立者。
注释掉代码也是同样，咱们用版本控制工具能够轻松找回之前的代码，不须要的代码能够直接删掉，而不是留一个注释掉的代码放在那里。
废话注释
/** The day of the month. */
private int dayOfMonth;
我不想多废话了……
结语
也许文中的观点和大多数人的思惟相左，可能个人有些观点是错的，欢迎你们和我讨论注释到底是否必要。最后若是以为文章不错的话就帮忙点个赞或者转发一下吧。
本文分享自微信公众号 - 代码洁癖患者（Jackeyzhe2018）。
若有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一块儿分享。