1.模块描述

模块是为了实现某一功能的函数的集合，文件名使用缺省的后缀，在每一模块的开头应有如下的描述体：

1
2
3
4
5
6
7
8
9
10
/******************************************************************************
***
* PROJECT CODE ：项目代号或名称 *
* CREATE DATE ：创建日期 *
* CREATED BY ：创建人 *
* FUNCTION ：模块功能 *
* MODIFY DATE ：修改日期 *
* DOCUMENT ：参考文档 *
* OTHERS ：程序员认为应做特别说明的部分，如特别的编译开关 *
*********************************************************************************/

不同的修改人应在修改的地方加上适当的注释，包括修改人的姓名。另外，如有必要，要注明模块的工作平台，如单板OS、DOS、WINDOWS 等。注明适用的编译器和编译模式。

2.函数描述

函数是组成模块的单元，一般用来完成某一算法或控制等。在每一函数的开头应有如下的描述体：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/******************************************************************************
***
* FUNCTION NAME：函数名称 *
* CREATE DATE ：创建日期 *
* CREATED BY ：创建人 *
* FUNCTION ：函数功能 *
* MODIFY DATE ：修改日期 *
* INPUT ：输入参数类型(逐个说明) *
* OUTPUT ：输出参数类型(逐个说明) *
* RETURN ：返回信息 *
*********************************************************************************/

可选的描述有：
* RECEIVED MESSAGES：收到的消息 *
* SENT MESSAGES ：发送的消息 *
* DATABASE ACCESS ：存取的数据库 *
* CALLED BY ：该函数的调用者 *
* PROCEDURES CALLED：调用的过程 *
* RECEVED PRIMITIVES : 收到的原语 *
* SENT PRIMITIVES : 发送的原语 *
及其它程序员认为应有的描述。标题可以只大写第一个字母。例如：Function Name：

3.命名规则：

A) 函数： 函数名应能体现该函数完成的功能，关键部分应采用完整的单词，辅助部分若太长可采用缩写，缩写应符合英文的规范。每个单词的第一个字母大写。如：ShowPoints，CtrlDestBoard，SendResetMsg 等。 B) 变量： 变量的命名规则部分采用匈牙利命名规则(鼓励完全使用匈牙利名规则)。变量的第一个或前两个字母小写，表示其数据类型，其后每个词的第一个字母大写。推荐的类型前缀如下：
规范
如iCurrentValue，uTransitionCount 等。对于其他复合类型或自定义类型，请用适当的前缀来表示。除局部循环变量外，不鼓励单个字母的变量名。
对于常用的类型定义，尽量使用WORD、BOOL、LPWORD、VOID、FAR、NEAR 等惯用写法，避免使用char、long、void、far、near 等小写格式。

4.书写风格：

A) 函数：函数的返回类型一定要写，不管它是否默认类型，函数的参数之间应用一逗 号加一空格隔开,若有多个参数，应排列整齐。例如： 

1
2
3
4
5
int SendResetMsg( PTLAPENTITY pLAPEntity, int iErrorNo ) 
{ 
	int iTempValue; 
	. . . 
}

函数的类型和上下两个括号应从第一列开始，函数的第一行应缩进一个TAB，不得用空格缩进。(按大多数程序范例，TAB 为四个字符宽，我们规定：TAB 为四个字符宽。)

B) 语句：循环语句和if 语句等块语句的第一个大括号‘{’可跟在第一行的后面，接 下来的语句应缩进一个TAB，如： 

1
2
3
4
5
6
7
for ( count = 0 ; count < MAXLINE ; count++ ) { 
	if ( (count % PAGELINE) == 0 ) 
	{ 
		. . . 
	} 
	. . 
}

也可另起一行，如： 

1
2
3
4
5
6
for ( count = 0 ; count < MAXLINE ; count++ ) 
{ 
	if ( (count % PAGELINE) == 0 ) 
	{ . . . } 
	. . 
}

两种写法在世界著名的程序员手下均可见到，我们尊重个人的习惯，但推荐使用后一种写法。复杂表达式(两个运算符以上，含两个)必须用括号区分运算顺序，运算符的前后应各有一空格，习惯写在一行的几个语句(如IF 语句)，中间应有一空格，其它语句不鼓励写在同一行。
空格加在适当的地方，如 if ( ; for ( ; ) {;
语句的上下对齐也可使程序便于阅读，如： 

1
2
3
myStruct.iFirstNumber = 0; 
myStruct.lSecondNumber = 1;
myStruct.pThePoint = NULL;

C) 常量：常量一般情况下可用宏定义，用大写的方式，单词之间用下划线隔开 如：

1
2
#define MAX_LINE 100 
#define PI 3.1415926

不鼓励在程序中出现大量的数字常数。
注：对于一些有必要说明的缩写，可以在模块描述内加以说明。

5.头文件：

头文件一般包括了数据结构的定义，函数原形的说明，宏定义等，不许包含函数体和变量实体，文件名使用缺省的后缀.h，不使用类似.DEF 等非标准的后缀名，头文件的开始可包括如下的注释：

1
2
3
4
5
6
/********************************************************************************
* CREATE DATE：创建日期 *
* CREATED BY ：创建人 *
* MODIFIED BY ：修改人 *
* USED BY ：由哪些模块使用 *
*********************************************************************************/

为了避免重编译，应加上条件编译语句，如文件headfille.h 应包含下列语句：

1
2
3
4
5
6
#ifndef __HEADFILE_H
#define __HEADFILE_H
.
.
.
#endif

6。注释：

注释是源码中非常重要的部分，不应少于源码行数的15%，我们希望能达到25%或更多。
注释用中英文都可以，但应易读易懂。不要在一个语句的中间插入注释。