谈代码注释

时间:2024-04-01 14:59:42

        只要写代码,就会遇到代码注释的问题。在不同的公司,不同的项目组,不同的项目中,可能会有不同的注释标准。有些标准让我们感觉很受益,有些则让我们感觉很反感。而对于没有明确标准的项目,我们往往会遇到“百家齐放,百家争鸣”般的注释。我无法给出一个明确的标准,只是在此探讨下:什么样的注释不应该写,什么地方需要写注释。(转载请指明出于breaksoftware的csdn博客)

“不”的原则

不是每行代码都需要写注释

        这个原则源于之前我和同事的一个争论。当时我们讨论代码注释该怎么写的问题,最终同事抛出这么一个观点:“我之前在X为干过,那儿就需要每行代码都写注释,所以我们应该执行这样的标准”。想必大家都可以猜到那是一家什么公司,但是从我个人角度分析,同事之前可能去的是一家假的“X为”公司。因为我觉得那个公司不应该如此没有技术品味吧?

        之后的探讨,我们将以画作为例。因为画是一种艺术表达,而我们的代码也应该写的和艺术品一样,表达出一种美。下图是梵高的《向日葵》原作,图中只有若干向日葵花、花瓶、地面(或者说是承载体)等元素。

谈代码注释

        假如我们对这份“代码”每行加一个注释,则呈现如下

谈代码注释

        各位看官感觉如何?我觉得如果梵高画的如果不像向日葵的话,这样搞点“注释”可能还有存在的意义。但是如果作品足够表意,那么再加上注释就是画蛇添足。这种为写注释而写注释是非常不可取的。为什么呢?因为

  • 增加编码人员无价值的工作量
  • 让编码人员降低对自己代码质量的要求,因为“反正要写注释”,叫index还是叫xpoesiejd无所谓。
  • 让对自己编码有艺术美感的编码人员产生抵触。比如我们要是让梵高给他原作加上上图一样的注释,我想梵高可能早就不想活了。

        但是我相信我同事可能说的是“真”的,但是这个“真”被我打了一个引号。因为我怀疑他之前可能在一家给X为干活的外包公司工作。也许X为的确有严格的代码注释量要求(也许“注释行数”/“代码行数”>0.5),于是这家外包公司就做了一个“任何一行代码都要写注释”的要求。我想如果他们真的这么去执行了,代码的注释量的确是上去了,但是或许注释的质量降低了,或者工作效率降低了。

不要写废话

谈代码注释

        上图是欧仁·德拉克罗瓦的著名油画《*引导人民》。这幅作品是为了法国七月革命而作,最前方的那个女性是克拉拉·莱辛,象征着*女神。她左手边男孩象征着阿莱尔,右手边戴大礼帽的男性象征着资产阶级,贝雷帽男性则象征着工人。可以见得这幅画包含了大量的背景知识。但是如果我们用废话注释它就是

谈代码注释

        是不是要抓狂?对于这样显而易见的信息写注释就是“废话”!

不要写错误的注释

谈代码注释

        上图是徐悲鸿的著名油画《田横五百士》。我们抛开这幅画的时代意义,单从历史画角度来看,大师给我们传达了一个错误的信息——人物的着装不符合故事地域年代(秦末齐国地区)。如果该幅画没有留下名字,后人通过画作的衣着信息(可以看成是一种注释)对该画所表达的故事进行推理时,可能出现断代错误,从而得出的故事和作者想表达的不同。

不要乱留名

谈代码注释        

        这幅是元代赵孟頫的《水村图卷》。请注意一下右上角那个大大的、红红的、方方正正的印章——乾隆御笔之宝。可能你会觉得乾隆爷给这幅画加盖了自己的印章,会导致该幅画价值大大增加,但是实际效果是恰恰相反。乾隆爷是有名的毁画大师,他经常在一些有名的作品上胡乱加盖自己的印章——留名。于是这些画作经他这么一折腾就会贬值。连乾隆爷的名字都那么不值钱,我们何必要在代码中乱留名呢?

        但是如果这份文件是你编写的,你还是要在版权信息中写入你的名字。这就和中国古人画作一般都会自己签名和盖自己印章一样。

        可能你会辩解,说:我添加的这段逻辑非常重要,我要留名以便以后有人能找到我。我觉得这个问题应该这么看:如果你的代码重要程度可以颠覆原作,我觉得你可以考虑重写一份并署上自己名字;如果没那么重要还是把留名交给原作者吧,毕竟你的成果是在他基础之上获得呢。

不要注释掉代码

        我想这个问题是最最常见的。大家翻翻自己项目的代码,可能都会遇到这种现象。当我们不需要一段代码时,可能也会估计是“永远不用了”还是“暂时不用了”。于是很多人对“暂时不用了”的代码使用注释方式使其无效。但是一般来说,这种“暂时不用了”的代码很有可能就是“永远不用了”,而人们已经忘记要去删除它了。这个现象在实际项目中比比皆是。所以个人觉得:不要的代码要果断删除。即使以后真的要用了,我们可以使用代码管理工具(svn或者git)方便的找回。

        下图是库尔贝的油画《受伤的男人》。其实作者在呈现这幅画之前,画布上画了一个女性头部。可能作者觉得这块逻辑可能没用了,于是就用黑色把“她”抹去,从而也成就了这幅名画。假想作者如果使用“注释”的手段将这颗头颅保留在画作中,将是如何吓人的一幅场景。

谈代码注释

不要写小故事

        在工作中,可能某个类的设计思路来源于和产品经理或者技术经理的思想碰撞,可能这个过程很精彩,有些编码者就将整个故事用注释的方式放在代码中。也有可能这个类和历史上一个著名人物有关,比如我们要编写斐波拉契数列实现,就将斐波拉契平生故事放到代码里。我觉得这些内容放在代码中是非常不合适的,也许你觉得很精彩,但是别人很有可能不关心啊。

        比如下图是米开朗琪罗的《耶稣受难》

谈代码注释

        现在我们觉得耶稣受难前“最后的晚餐”故事很精彩,于是我们把这段《新约圣经》“注释”到画作中

谈代码注释

        米开朗琪罗如果这么作画,可能现在我对他的认知中少了“画家”这一项。

不要有宗教倾向

        这个问题在国内不算太大的问题。因为程序员大部分是无神论者。当我们看到“佛祖保佑”或者“God save me”是往往是莞尔一笑。但是我们不能假设以后阅读这份代码的人没有宗教信仰,也许他信奉的和你正好相反呢。代码是没有宗教的,编码者是有的。

        我们比较常见是的“佛祖保佑 永无bug”

谈代码注释

        个人比较反感这种做法。所以我会在自己的项目中,将这种注释都删掉。假如我们的代码要依靠神来保佑,我只能质疑你代码的质量是不是已经超神了。我们还是要信奉二进制的。

不要博人一笑

        代码是严谨的逻辑表达,不要写一些逗人开心的内容。可能上例中“佛祖保佑,永无bug”在一些编码者看来只是为了博人一笑。但是我觉得阅读代码是一件需要连续动脑筋的事,如果我们阅读过程被这些“笑话”不停打断,那么最终的理解效率得有多低?

        比如著名的《清明上河图》,它包含了大量的社会信息。假如我每隔一段注释一个笑脸,那么这幅画可能就没那么高的艺术价值了。

谈代码注释

不要批判前人

        写出完美的代码的确是非常稀少的。所以我们阅读别人代码时,往往可以发现很多问题。在感觉不爽时,可能心中默默鄙视一下作者;再不爽时,可能和同事数落一下作者;再再不爽时,可能就要在代码中批判一下作者。但是这种注释对代码是有意义的么?而且并不是我们总是对的。由于对问题的理解深度、角度不同,编码者就是可能会写出让你不满意但是符合他自己原则的代码。

        比如梵高的《星空》

谈代码注释

        像我这种鉴赏能力比较差的,的确很难说出他画的哪儿好了。假如我给这幅画做了如**释

谈代码注释

        我想我并不会获得别人的赞许,可能全是对我的鄙视。那怎么办?我觉得我应该去画一幅符合我心目中“星空”的油画,这样供其他人在我和梵高中做个选择。或许这是一种自不量力,但是这却是一种对原作者的尊重。

“要”的原则

        说了这么多“不”的原则,其实我知道我还是没有说全。但是我们换个角度,如果我们知道“要”的原则,然后对其取反,就是涵盖所有“不”的原则了。

        在讨论这个话题之前,我先说下我对代码和注释的认识。

        首先我认为代码要写的和注释一样表意。也就是说我们要穷尽自己的思想,努力掌控每个名词、每个动词、每个换行、每个空格、每个组织形式以达到让代码可以自说明逻辑及业务。

        其次代码和注释应该是一个整体。往往一份文件包含代码和注释两部分,而阅读这份文件也有两个主体——编译器和人。编译器只是通过代码来获得逻辑信息,而人的要通过代码和注释一起理解逻辑和业务。

        基于第二点,我认为一份文件最好只有一个故事线——只需要用代码去表达,因为它是人和编译器同时可以去理解的。如果一个故事经过两个人去讲述,随着时间推移,最终会变成两个故事。这是非常可怕的。

        所以我的观点是:如果代码足够表意,且不违背常理,不应该去添加注释。反之则需要加注释。

        但是现实社会中,有时候很难做到不违背常理。因为我们这个世界随机性太强,有时候我们就要放弃一些我们认识的“常理”去达到期望的目的。这个时候我们代码的表达能力可能就是不足的了,就需要注释来表达。

        比如齐白石的画作中,寿桃往往是用来祝寿的

谈代码注释

        这个常理我们中国人都可以理解。但是假如我们看到下面这幅画,你觉得他是齐白石用来干嘛的?

谈代码注释

        它其实也是用于祝寿的。它是齐白石向蒋公祝60大寿时送的,和这幅画一起送的还有一副对联——人生长寿,天下太平。完整的版本是

谈代码注释

        假如觉得这副对联还不够表达“潜台词”,则上联左上侧“主席寿”几个字则可以完全说明了吧。

        这幅《松柏高立图》在2011年以4.255亿被拍卖,而它则是我认为需要写“注释”的一个典型代表。