C语言程序注释风格

良好编程习惯的养成对于一个程序员的发展非常重要，而注释对于一份程序来讲又是一个必不可少的组成部分，今天来研究一下C语言程序的注释风格。

注释是源码程序中非常重要的一部分，一般情况下，源程序有效注释量必须在15%以上。

注释的原则是有助于对程序的阅读理解，所以注释语言必须准确、易懂、简洁，注释不宜太多也不能太少，注释的内容要清楚、明了、含义准确，防止注释二义性，该加的地方一定要加，但不必要的地方一定不要加。

一、模块描述

模块描述中应该包括模块名、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等等。例如：

Module Name:  
Module Date:  
Module Auth:  
Description:  
Others:  
Revision History:  
Date Rel Ver Notes: 
XX/XX/XXXX X.X

二、头文件描述

头文件一般包含了数据结构的定义，函数原型的说明，宏定义等等，不许包含函数体和变量实体，文件名使用缺省的后缀.h，头文件的注释如下：

/*****************************************************************
 * Module Name:
 * Module Date:
 * Module Auth:
 * Description:
 * Others:
 * Revision History:
 * Date Rel Ver Notes:
 * XX/XX/XXXXX.X
*****************************************************************/

三、函数描述

函数的头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系等。例如：

/*****************************************************************
 * Function://函数名称
 * Description://函数功能，性能等的描述
 * Calls://备货单本函数调用的函数清单
 * Called By://调用的本函数的清单
 * Input://输入参数说明，包括每个参数的作用、取值说明及参数间关系
 * Output://输出参数的说明
 * Return://函数返回值的说明
 * Others://其他说明
*****************************************************************/