码农的自我修养-对代码注释的理解

如何写好代码注释是一个老话题，可以说一千个程序员就有一千种不同的理解。下面是从我自己工作中所看到的，所听到的；结合自己编码的体会谈一下自己的想法。

对代码注释的态度大致有三种误区：

1. 注释很重要，每一行代码都要写注释。

2. 注释可有可无，为了应付公司的编程规范，QA的审查，开始拷贝一些函数头注释，拷过去什么都不改，连原作者名都不改，只为满足代码注释率的要求。

3. 无需注释，代码即注释。

第一种：新员工热情很高，也很有责任心，导师或者项目经理说要把注释写清楚啊。于是乎就屁颠屁颠的每个变量，每个分支，每行代码都加上注释。有时候写了一句注释生怕别人不理解，在加一句注释来注释前一句注释。

写了很多日后自己看起来都会发笑的注释：


工作久了再来回过头来看这些代码注释，犹如脱裤子放屁般淡定地陈述了一句非常正确的废话。但是，谁没有当年呢，谁没有装B的时候。回味一下也是一段非常有意思的记忆。

第二种：业务基本上混熟了，也能在项目中承担一些核心的任务。觉得编码就是体力活(有时确实也是)，只要功能实现了，代码那怕写得像一坨si也无所谓。拷贝拷贝就OK了。

这个阶段往往开始考虑是走技术路线还是走管理路线了，走技术路线是走业务分析路线还是走架构设计路线。如果是有抱着前面描述想法的建议走业务分析路线或者管理路线，估计你对编码没多大兴趣。我认识一个人，开发时写的代码在后续版本维护和增量开发过程中无法扩展，改着改着几乎删了重写了；但这哥们业务研究的深入，转行做SE，现在转入Marketing,也混得风生水起。所以说不想写代码，写烂代码并一定就是你的错，可能你的兴趣就不在这里，找准自己的方向。

第三种：读过两本大师著作，不知道从哪听到了“代码即注释，代码即设计，代码即文档，代码即XXX”。

总之，代码注释越少越是显得自己牛X 。有时候维护的过程中或者代码检视的过程中看到这样的代码，大函数，圈复杂度老高，夹杂中式英语，全篇无注释。看到有歧义的地方想问一下都不知道问谁。真想吼一声：请注释你那该死的代码，你看它就是一坨si。

我们倡导代码自注释，通过恰当的命名，合理的结构划分让代码说话。但是不得不承认，代码作为人与计算机交互的语言，它的表达力，可理解性和人与人之间交流所使用的，经过千锤百炼的自然语言相比还是比较弱的。恰当有效的注释不仅是值得鼓励的而且是必须的。

通过实际经验对比发现：真正的编程高手不光代码写的漂亮，注释也写得相当漂亮，很多时候寥寥几笔注释起到画龙点睛的作用。而信仰并实践着代码即注释的人大部分都是半桶水。可以说看一个程序的代码写得怎么样，就看他的注释写得怎么样。

下面说说我对好的代码注释的理解：

1、注释首先要告诉维护的人这段代码是谁写的。

很多代码没有函数头注释，不知道是不屑写还是怕写。这不是一个好习惯，由于代码从开发到维护经常会换几拨人，新手未必能理解你当时的意图，这时能找人问一下是多么重要。将心比心，如果让你去维护一大块代码，看不懂又不知道问谁，估计也忍不住要破口大骂。

虽然现代的软件开发都是有版本控制，比较版本树能找到谁写的代码。但是，日积月累每个文件的版本节点数百个，从里面去找出某个函数，某处修改是谁写的也是很难得。

从我个人的理解，写代码不写函数头注释要么是太自信，要么是太不自信。自信是觉得代码写得很好了，很容易理解；不自信是代码写得太烂了，怕被人揪出来骂。

2、注释不是描述代码做了什么而是描述为什么这么做。

如上面的举例，注释将代码做的事情用语言再描述一遍，其实是画蛇添足。维护的人或者看代码的人，最想知道的是为什么这么做，是为了解决什么特殊问题吗？有没有什么复杂的业务背景。至于怎么做，看代码就知道了。

当然，对于业务逻辑实在太复杂的部分。看代码不能一下就看出个所以然来，通过一段文字说明，把关键点点出来，还是很有好处的。

3、注释描述的内容应该和代码是一致的。

这个就不说了，做过软件开发的人都知道。修改代码时未同步修改注释，注释成了误导。错误的注释比没有注释更糟糕。

参考这个。你说是该信代码呢还是信注释。


4、函数头注释应该描述函数调用的前置条件和后置条件。

函数作为供他人调用的一个接口，需要有它的使用说明书：在什么场景下使用，使用后会产生什么样的后果，使用须知等。比如该函数返回的指针需要调用方主动释放内存，如果调用方没有释放就会导致内存泄露。

5、取一个有意义的函数名，让它自注释。

函数是一个功能单元，做一件事情。函数名最好能定义为动宾结构，最好能具体一点。比如校验用户名，校验密码可以是CheckUserName,CheckPassword。如果是一个比较空泛的名称就不好理解，像DoChecking之类的。

开发过程中经常看到这样的情况：某个功能要处理A，B，C三件事，拆分成三个函数，函数名就是DoA, DoB, DoC。只能说太随意了，还可以再斟酌一下，更具体一点。

6、取一个好的变量名，让人不易误用。

见过字符串变量就直接定义叫str，某个结构体量定义叫st。或者有时候函数中的临时变量不知道定义什么名称，干脆叫temp1, temp2,temp3…。抓狂

7、好的代码注释应该告诉后来人维护的思路。

维护过程中发现好的代码注释，注释不仅展示了作者清晰的思路，还将作者对后续可能出现的变化的思考也融入进来。作者在写代码时已经考虑了后续版本的需求哪里可能会变化，变化后只要怎么修改一下哪里的代码就可以支持。这样的代码注释看起来很舒心，作者是有思想的，也是负责任的。