专栏首页代码洁癖患者代码洁癖系列(四):可忽略的注释

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

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

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

宫保鸡丁

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

//宫保鸡丁
地三鲜

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

注释不能拯救糟糕的代码

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

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

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

if (employee.isEligibleForFUllBenefits())

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

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

法律信息

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

提供信息的注释

// 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;

我不想多废话了……

结语

也许文中的观点和大多数人的思维相左,可能我的有些观点是错的,欢迎大家和我讨论注释究竟是否必要。最后如果觉得文章不错的话就帮忙点个赞或者转发一下吧。

—END—

本文分享自微信公众号 - 代码洁癖患者(Jackeyzhe2018),作者:Jackeyzhe

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2018-08-31

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Redis命令详解:Geo

    用法:GEOADDkey longitude latitude member [longitude latitude member …]

    Jackeyzhe
  • Redis命令详解:Connection

    最近在学习Redis的相关知识,上一篇我们也介绍了Redis的安装方法和基本数据结构,后面就打算开一个新的系列文章:Redis命令详解。既是对基础的巩固,也是为...

    Jackeyzhe
  • 【译】大O的友好指南

    原文链接:https://medium.com/@daily_javascript/a-friendly-guide-to-big-o-ea781c5f68f0

    Jackeyzhe
  • C++注释风格建议

    有个笑话,一位从不写注释的程序员在编写一段复杂的代码时,骄傲地认为这段代码只有自己和上帝知道它是干嘛的,等过了一段时间再回顾时,发现没有注释,感叹到这段代码现在...

    Dabelv
  • 客户让你给代码加注释怎么办?

    作为乙方,我以前听过一些同事说客户要求给代码加注释,一开始自己不以为然,直到有一天这件事情发生在我身上:某大有可为的项目接近尾声,准备下项目前一周,PM说接到客...

    袁慎建@ThoughtWorks
  • Python注释用法

    在Python中的注释与其他语言相比有很大的不同,但使用起来也很简单。在Python中有两种注释,一种是单行注释,一种是多行注释。单行注释适用于简短快速的注释(...

    marsggbo
  • 代码里注释写太多,会挨打吗?

    前几天,有个同行朋友在我的微信上留言,问我项目代码里注释写太多会挨打吗?顺手还给我甩了一张截图,上面密密麻麻的全是手工注释。

    闰土大叔
  • Redis作者谈如何编写系统软件的代码注释

    顶顶大名的Redis作者谈如何在Redis这样系统软件上进行代码文档注释,以下是九种注释类型的大意说明: 很长一段时间以来,我一直想在YouTube上发布一段...

    lyb-geek
  • Java-初级编码规范

    良好的编码规范和习惯会让你的代码锦上添花,同时也会大大的增加团队协作开发的效率,避免很多细节的问题,从而大大的提高你的代码的可阅读性,同时也是一个优秀开发者的必...

    老九学堂-小师弟
  • Java注释:您想知道的一切

    注释是元数据的一种形式。它提供有关程序的数据,该数据不属于程序本身。注释对其注释的代码的操作没有直接影响。注释是在Java语言规范的第三版中以Java语言首次引...

    用户7466307

扫码关注云+社区

领取腾讯云代金券