关于程序注释的使用

程序注释是书写规范程序时很重要的一个内容，下面对注释的一些说明：
1. 注释的作用：方便代码的阅读和维护（修改）。
2. 注释在编译代码时会被忽略，不编译到最后的可执行文件中，所以注释不会增加可执行文件的大小



。
3. 注释可以书写在代码中的任意位置，但是一般写在代码的开发或者结束位置。
4. 修改程序代码时，一定要同时修改相关的注释，保持代码和注释的同步。
5. 在实际的代码规范中，要求注释占程序代码的比例达到20%左右，即100行程序中包含20行左右的注释。

 

程序注释规范应包括以下三方面：

一、文件头部注释
    在代码文件的头部进行注释，这样做的好处在于，我们能对代码文件做变更跟踪。在代码头部分标注出创始人、创始时间、修改人、修改时间、代码的功能，这在团队开发中必不可少，它们可以使后来维护 / 修改的同伴在遇到问题时，在第一时间知道他应该向谁去寻求帮助，并且知道这个文件经历了多少次迭代、经历了多少个程序员的开发和修改。

样本：

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

** 作者： 张三

** 创始时间： 2010-12-12

** 修改人：lisi

** 修改时间： 2010-12-15

** 修改人：王五

** 修改时间： 2010-12-20

** 描述：

**    主要用于产品信息的资料录入， …

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

 

二、函数、属性、类等注释

请使用 /// 三斜线注释，这种注释是基于 XML 的，不仅能导出 XML 制作帮助文档，而且在各个函数、属性、类等的使用中，编辑环境会自动带出注释，方便你的开发。以 protected ， protected Internal ， public 声明的定义注释都建议以这样命名方法。

例如：

/// <summary>

/// 用于从 ERP 系统中捞出产品信息的类

/// </summary>

class ProductTypeCollector

{

       …

}

 

三、逻辑点注释   

在我们认为逻辑性较强的地方加入注释，说明这段程序的逻辑是怎样的，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG 。在注释中写明我们的逻辑思想，对照程序，判断程序是否符合我们的初衷，如果不是，则我们应该仔细思考耀修改的是注释还是程序了…

四、变量注释

    我们在认为重要的变量后加以注释，说明变量的含义，以方便我们自己后来的理解以及其他人的理解，并且这样还可以在一定程度上排除BUG. 我们常用/// 三斜线注释。

 

/// 用于从 ERP 系统中捞出产品信息的类

class ProductTypeCollector

{

    int STData;/// <summary>

       …

}