5.1 多种注释形态
5.1.1 不包含强调内容的单行注释
/* 单行注释常用于注释程序主体代码 */
5.1.2 包含强调内容的单行注释
/*---> 注意：需要处理错误信息 <---*/
/*>>>>> 精密计算例程 <<<<<*/
5.1.3 不包含强调内容的多行注释
/*
* 可通过此种形式编写包含多行语句的注释
* 没有需要特别强调的内容，但需要用较长的句子进行更准确的说明时，使用此类注释
*/
有时，需要在中段插入特殊字符区分注释中的内容，如下所示：
/*
* 校验模块的输入值
* -----------------------------------------------------------------
* input1：总计，不能使用浮点数
* input2：合计，用于与平均值比较，判断二者之间的误差是否过大
*/
5.1.4 包含强调内容的多行注释
/*******************************************************/
/*!!!!!!!!!! 警告（warning） !!!!!!!!!!*/
/*******************************************************/
/* 需要特别注意这段程序，因为它时列车控制模块 */
/* 所有数据必须经过精确校验，并通过数十次测试以确保万无一失 */
/*******************************************************/
5.2 区分单行注释和注释框
单行注释用于补充说明程序主体语句，无法提供足够多的程序或函数的信息。因此，需要说明程序或函数时，应该采用多行注释。
注释框包含程序名、目标、编写者、修改者、编写日期和修改日期等众多信息，方便人们理解程序。实际上，程序员可以从注释框提供的信息中获得比程序代码本身更多的线索。因此，如果希望成为经验丰富的程序员，就应该在程序或函数（C++程序则包含类在内）的起始部分采用注释框。
程序主体语句中尽量不使用注释框，若实在需要，则应采用单行注释，主要标注程序代码本身没有体现的信息。
5.3 添加“变量字典编写专用注释”
int area; /* 面积：计算正在施工中的建筑物的地基面积 */
int wide; /* 宽度：以米为单位，计算地基横向长度 */
int height; /* 高度：以米为单位，计算地基纵向长度 */
这种方法称为“变量字典编写专用注释”，简称“字典注释”（diction comment）。
字典注释不仅能够在程序内部描述各变量作用。假设一个程序单元包含数十个乃至数百个模块，各模块都如上所示，为所有变量编写了严格的字典注释。那么，只要将各模块中变量声明的部分复制并保存到同一个文件，则该文件即可视为能够说明所有变量的字典。
这种字典在检查程序时非常重要。外部变量和静态变量、静态变量和自变量中，如果存在变量名相同的情况，变量之间就会产生冲突。可以通过字典注释事先确认各个变量功能以及各自的变量名，以避免此类情况。
提示：C、Java、C++等几乎所有编程语言都需要注释，并且存在程序能够将所有注释单独提炼为一个独立且完备的文本文件。Java中的javadoc就是最具代表性的例子。注释可以成为一种文本化工具，所以严格地为每个变量添加注释有助于利用这种文本化工具编写变量字典。
5.4 向程序插入伪代码
注释的存在是为了使程序便于理解，即为了使包含程序编写者在内的所有人都能轻松理解程序的“目标和逻辑”。
程序的“目标和逻辑”中，“逻辑”可以用伪代码补充。在程序起始部分用注释形式标注伪代码后，程序的整体脉络就一目了然。
5.5 通过注释标注程序目标
伪代码的主要作用是体现程序的“逻辑”，而不能完全展现“目标”。如果程序本身没有明确标注目标，那么人们阅读该程序时就不得不根据伪代码进行推测。为了减少这种麻烦，编写程序的人最好事先将程序目标用简单的一两行文字进行标注，毕竟自己比任何人都要了解该程序。
标注程序目标时，应该遵守“六何原则”，如下所示：
/*
* 何时（when） 编写日期：2004年 2月 10日
* 何地（where） 场 所：oo 物产 SI 事业部 培训组
* 何人（who） 编 写 者：洪吉童 代理
* 何事（what） 代码性质：C语言代码 约有20行
* 为何（why） 编写理由：最大值、最小值教学
* 如何（how） 编写环境：控制台
*/
5.6 程序起始部分必须添加头注释
注释大致可分为“主体注释”和“头注释”两类，主体注释位于程序代码之间，用于说明对应部分的作用；头注释位于程序起始部分，用于指出程序的题目、作者、目标等。COBOL这种语言要求必须有头注释，但以C语言为首的大多数语言则规定，是否添加头注释取决于程序员的意愿。尽管是可选项，但我们仍希望能够“半强制”地添加头注释。
5.7 在等于运算符旁添加注释
比较是否相等地运算符==很容易与赋值运算符=混淆，因此，首先要做的是添加注释。例如：
while(count == 1; count++; count <= 100) { ... } // count从1开始计数
if(isThis == TRUE) { ... } // 如果isThis的值为真
5.8 在大括号闭合处添加注释
int main () {
// ......
if () {
// ......
if () {
// ........
} // end inner if
} // end outer if
} // end function main
5.9 在函数内部添加详细介绍函数的注释
对于那些一般情况下已经拥有足够多的说明文档并别广泛应用的函数，没必要非得添加注释。但其他情况下，无论是只在一个项目还是一个公司内使用的函数，都应该留下详细注释。特别需要注意，应该严格记录如下内容。
- 函数的目标
- 各参数允许的数据类型及含义
- 返回值应用于何处
5.10 注释标记原则
- 代码本身足以说明问题时，不必添加注释
- 代码本身不足以说明问题时，尽可能添加详细注释
网友评论