1.3 程序注释

1.3.1程序注释是程序员与日后的程序读者之间通信的重要手段之一，注释分为文件注释、函数注释和功能注释。

1.3.2正规程序的注释应注意：

——注释行的数量占到整个源程序的1/3到1/2。

1.3.3文件注释位于整个源程序的最开始部分，注释后空两行开始程序正文。它包括：

——程序标题。

——目的、功能说明。

——文件作者、***修改日期等说明。

例：

./

(空一行)

标题： Demo.c

功能： 测试VxWorks的各种系统调用。

说明：

该程序测试各种VxWorks的系统调用函数。包括任务(taks)的创建、挂起及任务间通过信号灯实现同步，通过消息队列进行通讯。

程序创建了两个任务：一个高优先级的任务和一个低优先级的任务。两个任务间通过一个二进制的信号灯进行同步，通过消息队列进行通讯。

当前版本： x.x

修改信息： 2000.06.05 John， Initial Version

2000.07.05 Tom， Bug xxxx fixed

/

(空2行，开始程序正文)

　1.3.4 函数注释通常置于每函数或过程的开头部分，它应当给出函数或过程的整体说明对于理解程序本身具有引导作用。一般包括如下条目：

——模块标题。

——有关本模块功能和目的的说明。

——调用格式

——接口说明：包括输入、输出、返回值、异常。

——算法。如果模块中采用了一些复杂的算法。

例：

file：//(注释开头应和上一函数空两行)

(注释开头与上一函数***一行间隔两行)

/

标题：assignmentComplete

功能：BSC=%26gt;MSC消息生成函数，生成assignment_complete指配完成消息(BSMAP消息) .

格式：

int assignmentComplete(int iCellId， int iServiceChannnelNum， char pszMSGData) throw(exception1， exception2)

输入：

int iCellId： MS所在的小区识别

iCellId取值：0x00-——0xff .4.

Q/ECC/BJ 010—2001

int iServiceChannnelNum：MS所占的业务信道号码

输出：

char pszMSGData：指配完成消息数据

返回值： 0x00正常

异常：exception1异常情况1， exception2异常情况2

/

( 注释后直接开始程序正文，不空行。)

1.3.5 功能性注释嵌在源程序体中，用于描述其后的语句或程序段做什么工作，也就是解释下面要做什么，或是执行了下面的语句会怎么样。而不要解释下面怎么做，因为解释怎么做常常与程序本身是重复的。

例： /把 amount 加到 total中/

total = amount + total;

这样的注释仅仅是重复了下面的程序，对于理解它的工作并没有什么作用。而下面的注释，有助于读者理解。

/将每月的销售额amount加到年销售额total中/

total = amount + total;

【编辑推荐】

1. 2011软考软件设计师：C语言代码规范问题(2)
2. 2011软考软件设计师：C语言代码规范问题(1)
3. 2011年软件水平考试软件设计师辅导资料(9)
4. 更多软考资料请点击51CTO软考专题