C语言编码规范
SWUST ROBOTEAM
编程规范
C 语言
SWUST Roboteam
Create Date:2007-04
Version: 0.90bate
C语言编码规范
SWUST ROBOTEAM
编码格式
I. 注释
注释是源码程序中非常重要的一部分，一般情况下，源程序有效注释量必须在15％以上。
注释的原则是有助于对程序的阅读理解，所以注释语言必须准确、易懂、简洁。注释不宜太多
也不能太少，注释的内容要清楚、明了，含义准确，防止注释二义性，该加的地方一定要加，但不
必要的地方一定不要加。
（1）模块（C文件）描述
模块描述中应该包括。版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志
等。 例如：
/***********************************************************
Module Name: //模块的名字
Module Date: //生成日期
Module Auth: //作者名字
Description: // 用于详细说明此程序文件完成的主要功能，与其他模块
// 或函数的接口，输出值、取值范围、含义及参数间的控
// 制、顺序、独立或依赖等关系
Others: // 其它内容的说明
Revision History:
Date Rel Ver. Notes
月/日/年 x.x //所进行的修改
***********************************************************/
/*----------------Includes---------------*/
//包含的头文件
/*------------Local Variables----------- */
//定义一些本地变量
/*------Local Structures and Typedefs ---*/
//要使用的一些数据结构
/*-----------Extern Variables -----------*/
C语言编码规范
SWUST ROBOTEAM
//使用到的一些外部变量
/*-------------Definitions---------------*/
//一些#defines及具体的函数实现
（2）头文件描述
头文件一般包括了数据结构的定义，函数原形的说明，宏定义等，不许包含函数体和变量实体，
文件名使用缺省的后缀 .h ，头文件的注释可如下：
#ifndef MODEL_H
#define MODEL_H
/***********************************************************
Module Name: model.h
Module Date: month/day/year
Module Auth: your name
Description: a short introduction of this module.
Revision History:
Date Rel Ver. Notes
month/day/year x.x [e.g.] Module created
***********************************************************/
/*----------------Includes---------------*/
//the head files that were included
//[e.g.] #include "head.h"
/*---------Structures and Typedefs-------*/
/*[e.g.] struct model{
char MemberOne;
int MemberTwo;
char MemberThree[3];
struct module *MemberFour;
}
enum BOOL {TRUE ,FALSE };
typedef struct module MODULE;
*/
/*---------------Defines-----------------*/
//[e.g.] #define MODLE 2
/*----------extern variables-------------*/
//the variables that were defined in other modules
//[e.g.] estern char ExternVariable;
C语言编码规范
SWUST ROBOTEAM
/*-----External Function Prototypes------*/
/* External Function Prototypes */
//the functions that were implemented in other modules
//[e.g.] extern unsigned char model(int Input[2]);
#endif
（3）函数描述
函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关（函数、
表）等。 例如：
/***********************************************************
Function Name: //函数名
Function Description: //函数功能、性能等的描述
Inputs: // 输入参数说明，包括每个参数的作用、取值说明及参数间关系。
Outputs: / /对输出参数的说明
Notes: // 本函数调用的函数清单及其他
************************************************************/
（4）其他注释
1. 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释
的。说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
2. 注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位
置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。
3. 对于所有有物理含义的变量、常量，数据结构声明(包括数组、结构、类、枚举等)，如果其命
名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应
放在其上方相邻位置或右方。 例如：
/* active statistic task number */
#define MAX_ACT_TASK_NUMBER 1000
#define MAX_ACT_TASK_NUMBER 1000 / / active statistic task number
4. 全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注
意事项等的说明。
5. 将注释与其上面的代码用空行隔开。 例如：
/* code one comments */
program code one
/* code two comments */
program code two
C语言编码规范
SWUST ROBOTEAM
6. 在代码的功能、意图层次上进行注释，提供有用、额外的信息。 说明：注释的目的是解释代码
的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注
释信息。 例如：如下注释意义不大。
/* if receive_flag is TRUE */
if (receive_flag)
而如下的注释则给出了额外有用的信息。
/* if mtp receive a message from links */
if (receive_flag)
II. 排版
（1）程序块要采用缩进风格编写，缩进的空格数为 4 个。把源程序中的Tab字符转换成4个空格；
一个缩进等级（Indentation Level）是4个空格；变量定义和可执行语句要缩进一个等级；
函数的参数过长时，也要缩进。
（2）程序块的分界符（如C/C++语言的大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用
它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、
while、switch、case语句中的程序都要采用如上的缩进方式。 例如：
for (...)
{
... // program code
}
if (...)
{
... // program code
}
void example_fun( void )
{
... // program code
}
（3）相对独立的程序块之间、变量说明之后必须加空行。
if (!valid_ni(ni))
{
... // program code
}
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
