C语言注释规范

C语言注释规范

1.注释原则

同一软件项目开发中，尽量保持代码注释规范和统一。

注释方便了代码的阅读和维护。

边写代码边注释，修改代码时要相应修改注释，保证注释和代码的一致性。

注释要简洁明确，不要出现形容词。

对于写的好的注释，我们将是第一个受益者。

大型软件开发中，通过别人的注释可以快速知道他人所写函数的功能，返回值，参数的使用。

2.文件头部的注释

示例：

/

* Program Assignment : 该文件的作用

* Author: 作者

* Date: 2013/8/6 14:34

* Description: 该文件的描述

*****/

/*

* Source code in :

源代码的路径

* Function List:

* initLinear 初始化线性表

* destoryLinear 释放线性表申请的空间

* isLinearEmpty 判断线性表是否为空

* isLinearFull 判断线性表是否为满

* getLinearElementValue 取得下标为index的元素的值

*/

注意：这个函数列表可以快速查询到我们想要了解的函数。

3.结构体，全局变量等的注释

示例：

typedef POLYNOMIAL USER_TYPE; /* 新的数据类型的描述*/

int a; /* 全局变量的作用*/

/* 说明结构体的功能*/

typedef struct LINEAR

{

USER_TYPE *data; /* 每个成员的意义(作用) */

int maxRoom; /* 每个成员的意义(作用) */

int elementCount; /* 每个成员的意义(作用) */

}LINEAR;

4.函数的注释

在逻辑性较强的的地方加入注释，以便其他人的理解，在一定的程度上排除bug。

示例：

/*

* Function Name: getLinearElementIndex

* Purpose: 取得元素的index值

* Params :

* @LINEAR linear 线性表实例

* @USER_TYPE var 类型为USER_TYPE的实例

* @int (*)() cmp 提供接口，让用户定义具体比较函数

* Return: int 返回元素的index值

* Limitation: 如果返回-1，则代表不存在var的元素

*/

int getLinearElementIndex(LINEAR linear, USER_TYPE var, int (*cmp)())

{

/*

* 如果逻辑太过复杂，这里写明该算法的过程和思路。

*/

boolean found = FALSE;

int i;

for(i = 0; i < && !found; i++)

if(cmp[i], var) == 0)

found = TRUE;

if(i >=

i = NOT_FOUND;

return i;

}