码农的自我修养——对代码注释的理解（转）

小甲鱼 · 发表于 2018-5-30 16:10:28

《零基础入门学习Web开发》

小甲鱼著

立即购买

马上注册，结交更多好友，享用更多功能^_^

您需要登录才可以下载或查看，没有账号？立即注册

×

码农的自我修养——对代码注释的理解（转）

转自 -> https://blog.csdn.net/ylforever/article/details/51171580

如何写好代码注释是一个老话题，可以说一千个程序员就有一千种不同的理解。

下面是从我自己工作中所看到的，所听到的，结合自己编码的体会谈一下自己的想法。

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

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

第一种

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

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

<!DOCTYPE html>
<html>
<head>
<title>定义文档内嵌代码</title>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="keywords" content="小甲鱼,Web开发,HTML5,CSS3,Web编程教学">
<meta name="description" content="《零基础入门学习Web开发》案例演示">
<meta name="author" content="小甲鱼">
</head>
<body>
<p>上面的内容哪来的？</p>
<script type="text/javascript">
document.write("I love FishC.com!");
</script>
</body>
</html>

复制代码

工作久了再来回过头来看这些代码注释，犹如脱裤子放屁般淡定地陈述一句非常正确的废话。但是，谁没有个当年呢，谁没有装个 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……抓狂 T_T

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

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