程序代码注释的探讨[未完待续]

 

在计算机学院学习已经五六年了，在学习理论和编写程序的时候会对一些遇到的问题进行思考，同时也希望和更多有丰富经验的同仁一起探讨。近来在完成一个面向对象课程的程序设计过程中，自己在代码中添加了大量的注释信息，然而在整个设计完成之后，回头再来回顾或修改自己的程序时发现这些注释没有给自己提供有效的信息，对于日后重新分析、理解和修改没有起到应有的提示作用。在网上搜索相关的规范和经验文章时，收获并不是很多，因此将自己遇到的问题和随后的思考与大家共同讨论，希望能够有更多的朋友关注并重视注释的重要意义，科学合理地运用代码注释。

        （1）注释的稠密程度：本人以往的程序注释都十分具体和详细，每条语句都附有注释。问题是注释只是描述性语言，与上下文缺乏连贯性，主要为本条语句的语法描述。这样对于查阅代码的人来说几乎没有提供有用的信息，因为阅读代码的人都懂得语句的语法含义，他需要的是这些连贯语句之间的关系和产生的算法特点。因此注释的多与少不是关键问题，提供有效信息才是注释核心目的，而且过多的注释会令代码界面凌乱，是读者难以在其中寻找到所关心的重要信息。

        （2）注释的形式：虽然各种语言都有各自的注释方式和语法规范，然而如何组织自己的信息以最有效地方式呈现在阅读者面前并不是一件容易的事情，体现了编写者的智慧和能力。因此我期望寻求一种较清晰明确的信息整合格式。

         [A]在程序代码的开头提供必要的整体代码的概括描述和作者的信息。以C++为例：

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

           *整个项目的名称和版本信息                                             *

           *本文件在项目中的角色、主要的功能、开发时间以及版本信息 *

           *开发者的信息，联系方式                                                *

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

     在这里突出强调一个文件所代表的部分在整个项目工程中的角色和所用。

          [B]关于函数的功能描述和使用方法说明。

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

           *函数的名称，参数以及返回值说明                              *

           *函数的功能，调用方式和使用说明（与其它函数之间的相互关系）*

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

     这里突出强调使用函数的方式和注意事项。在何种情况下调用，产生何种结果。

        （3）注释的内容：如上文所说的，如果注释只是进行本条语句的语法描述，那么它存在的意义就会大打折扣，毕竟从这些注释中，我们还是很难把握整体代码的逻辑关系和主体思路。将自己的设计思想融入注释中将有助于别人更容易地理解自己的程序。