本文转自:https://blog.csdn.net/ylforever/article/details/51171580程序员
如何写好代码注释是一个老话题，能够说一千个程序员就有一千种不一样的理解。下面是从我本身工做中所看到的，所听到的；结合本身编码的体会谈一下本身的想法。编程
第一种：新员工热情很高，也颇有责任心，导师或者项目经理说要把注释写清楚啊。因而乎就屁颠屁颠的每一个变量，每一个分支，每行代码都加上注释。有时候写了一句注释生怕别人不理解，在加一句注释来注释前一句注释。架构
写了不少往后本身看起来都会发笑的注释：函数
工做久了再来回过头来看这些代码注释，犹如脱裤子放屁般淡定地陈述了一句很是正确的废话。可是，谁没有当年呢，谁没有装B的时候。回味一下也是一段很是有意思的记忆。编码
第二种：业务基本上混熟了，也能在项目中承担一些核心的任务。以为编码就是体力活(有时确实也是)，只要功能实现了，代码那怕写得像一坨si也无所谓。拷贝拷贝就OK了。.net
这个阶段每每开始考虑是走技术路线仍是走管理路线了，走技术路线是走业务分析路线仍是走架构设计路线。若是是有抱着前面描述想法的建议走业务分析路线或者管理路线，估计你对编码没多大兴趣。我认识一我的，开发时写的代码在后续版本维护和增量开发过程当中没法扩展，改着改着几乎删了重写了；但这哥们业务研究的深刻，转行作SE，如今转入Marketing,也混得风生水起。因此说不想写代码，写烂代码并必定就是你的错，可能你的兴趣就不在这里，找准本身的方向。架构设计
第三种：读过两本大师著做，不知道从哪听到了“代码即注释，代码即设计，代码即文档，代码即XXX”。设计
总之，代码注释越少越是显得本身牛X 。有时候维护的过程当中或者代码检视的过程当中看到这样的代码，大函数，圈复杂度老高，夹杂中式英语，全篇无注释。看到有歧义的地方想问一下都不知道问谁。真想吼一声：请注释你那该死的代码，你看它就是一坨si。版本控制
咱们倡导代码自注释，经过恰当的命名，合理的结构划分让代码说话。可是不得不认可，代码做为人与计算机交互的语言，它的表达力，可理解性和人与人之间交流所使用的，通过千锤百炼的天然语言相比仍是比较弱的。恰当有效的注释不只是值得鼓励的并且是必须的。指针
经过实际经验对比发现：真正的编程高手不光代码写的漂亮，注释也写得至关漂亮，不少时候寥寥几笔注释起到画龙点睛的做用。而信仰并实践着代码即注释的人大部分都是半桶水。能够说看一个程序的代码写得怎么样，就看他的注释写得怎么样。
下面说说我对好的代码注释的理解：
一、注释首先要告诉维护的人这段代码是谁写的。
不少代码没有函数头注释，不知道是不屑写仍是怕写。这不是一个好习惯，因为代码从开发到维护常常会换几拨人，新手未必能理解你当时的意图，这时能找人问一下是多么重要。将心比心，若是让你去维护一大块代码，看不懂又不知道问谁，估计也忍不住要破口大骂。
虽然现代的软件开发都是有版本控制，比较版本树能找到谁写的代码。可是，日积月累每一个文件的版本节点数百个，从里面去找出某个函数，某处修改是谁写的也是很可贵。
从我我的的理解，写代码不写函数头注释要么是太自信，要么是太不自信。自信是以为代码写得很好了，很容易理解；不自信是代码写得太烂了，怕被人揪出来骂。
二、注释不是描述代码作了什么而是描述为何这么作。
如上面的举例，注释将代码作的事情用语言再描述一遍，实际上是多此一举。维护的人或者看代码的人，最想知道的是为何这么作，是为了解决什么特殊问题吗？有没有什么复杂的业务背景。至于怎么作，看代码就知道了。
固然，对于业务逻辑实在太复杂的部分。看代码不能一下就看出个因此然来，经过一段文字说明，把关键点点出来，仍是颇有好处的。
三、注释描述的内容应该和代码是一致的。
这个就不说了，作过软件开发的人都知道。修改代码时未同步修改注释，注释成了误导。错误的注释比没有注释更糟糕。
参考这个。你说是该信代码呢仍是信注释。
四、函数头注释应该描述函数调用的前置条件和后置条件。
函数做为供他人调用的一个接口，须要有它的使用说明书：在什么场景下使用，使用后会产生什么样的后果，使用须知等。好比该函数返回的指针须要调用方主动释放内存，若是调用方没有释放就会致使内存泄露。
五、取一个有意义的函数名，让它自注释。
函数是一个功能单元，作一件事情。函数名最好能定义为动宾结构，最好能具体一点。好比校验用户名，校验密码能够是CheckUserName,CheckPassword。若是是一个比较空泛的名称就很差理解，像DoChecking之类的。
开发过程当中常常看到这样的状况：某个功能要处理A，B，C三件事，拆分红三个函数，函数名就是DoA, DoB, DoC。只能说太随意了，还能够再斟酌一下，更具体一点。
六、取一个好的变量名，让人不易误用。
见过字符串变量就直接定义叫str，某个结构体量定义叫st。或者有时候函数中的临时变量不知道定义什么名称，干脆叫temp1, temp2,temp3…。抓狂
七、好的代码注释应该告诉后来人维护的思路。维护过程当中发现好的代码注释，注释不只展现了做者清晰的思路，还将做者对后续可能出现的变化的思考也融入进来。做者在写代码时已经考虑了后续版本的需求哪里可能会变化，变化后只要怎么修改一下哪里的代码就能够支持。这样的代码注释看起来很舒心，做者是有思想的，也是负责任的。