经验分享：程序注释的一些体会

         有良好的注释习惯，不一定是合格程序员；但没有良好注释习惯，一定不是合格程序员。

         程序注释，我体会比较深刻，因为我的机房收费系统重构就是因为注释写的不好。

         记得刚刚开始接触编程的时候，完全不懂注释的意义，但学习别人的代码时，发现人家都有注释，于是也学着用注释点缀自己的程序，经过将近两年的积累，我对注释有了比较深刻的认识，接下来就与大家共享一下自己的经验。

         前篇废话，其实关于注释的讨论、优点、注意事项等等，网上有很多很多，本小菜在此从实际应用角度出发，分享经验。

 

        一、注释可以帮助理清思路。

 

        写注释不仅仅是关爱他人，让别人维护起来更加轻松，实际上写注释对理清思路有很大帮助。

        正所谓代码未动，注释先行。举个形象的例子：

        用程序表达：如何把大象装进冰箱里？

         我们先不考虑实现细节，先用注释勾勒出大致步骤，如下：

         //打开冰箱门

 

        //把大象放进冰箱

 

        两步就搞定，看起来少点什么，很重要的一步，忘了关上冰箱门。

        //打开冰箱门

        

        //把大象放进冰箱

 

        //关上冰箱门

 

        这样看起来就很不错了，但是还缺点东西，面向对象编程，要先创建对象。

        //创建冰箱对象和大象对象

 

        //打开冰箱门

        

        //把大象放进冰箱

 

        //关上冰箱门

 

        这样就差不多了！面向对象语言一般都有垃圾回收机制，不用手动销毁对象。

         经过这么一个写注释的过程，基本理清了程序思路，避免出现逻辑混乱，又能避免出现一些低级错误。通过注释，不知不觉就写出了一段漂亮的代码。

         什么？你认为这是个与程序无关的例子？别忘了，程序源于生活，高于生活，这个例子不就是数据库操作的样本吗？

 

        二、注释要有深度。

 

         这是个很有意思的话题，注释没深度有多可怕，见下图：

        

        可见，没有深度的注释，无论是对自己还是对别人，都是一种伤害，无疑会给后期维护造成诸多不便，致使维护效率低下。

        图中的注释，完全是多余的，只是把代码描述了一遍，对理解程序没有任何帮助，反而会分散注意力。

        注释，既然写，就要写的有深度，它应该能直接指出矛盾所在，表明意图。比如写成这样：//判断返回值是否符合标记，如果不符合，将怎样….

        因此，写注释也要用心，避免出现垃圾注释。

 

        三、别忘了模块注释。

 

         上边提到的所有注释，都应该叫做局部注释，比局部注释范围大点的是方法、类注释，再大的就是模块注释。

         模块注释，从我一开始接触编程就经常羡慕别人能写出那么漂亮的模块注释，我是属于VB启蒙，印象最深刻的就是嗷嗷叫的老马，VB世界的泰斗，经常使用老马写的模块，看到人家的注释，简直就是享受。

         模块注释，至关重要，它基本阐述了整个模块的信息，是模块的宏观描述，主要包括：版权、逻辑说明、调用说明、版本等。让人一看就对整个模块了然于胸，无需去读代码，便能直接使用。这样模块维护起来，无疑会让人很舒服。

        附上一个比较全面的模块注释模版。

         /*************************************************

        编写者：

        小组成员：

        模块名称：

        模块功能：

        调用示例：

        依赖模块：

        创建日期：

        版本号：

        版权所有：

        修改日期：

        修改原因：

        **********************************************/

 

         但在自己实际编程时，却经常忘了写，琢磨着原因可能如下：

 

        n  模块注释一般是模块编写、测试完成时才写的，由于着急等因素，容易忽略。

        n  目前编写的程序比较小，没有那么轰轰烈烈，容易忘记完善模块注释。

 

        希望读者能认真体会，时刻谨记模块注释，不要像我一样。

        

 

        四、适当用注释代替删除，保留痕迹。

 

         很多情况下，代码要经过不断完善，最终才能成型，而在完善的过程中，可能有很多过渡代码，按照我的习惯，太长或者不太重要的过渡代码，直接删除；而那些比较关键，价值比较高的，则用注释保留下来，以后维护了可以提供一个参考。

         因为程序无所谓好坏，符合需求的才是最好的，目前正确的程序，不代表永远正确，神才知道哪天会用到那些过渡代码，如果我们适当保留，以后维护可以轻松许多。

        

         好啦，暂时就写到这，以后有什么新的体会、心得，接着分享！

        欢迎大家多多交流！

 

附：

 

写好程序注释的十三条建议：http://www.cnblogs.com/iyangyuan/archive/2012/12/05/2803842.html