嵌入式C语言编码规范参考

1 总则

1.1 目的

本规范主要目的是定义基于嵌入式C 编码的总体规范，确保编码的规范性，提高程序的可维护性。通过遵循共同的编码规范，程序开发人员可以保持代码一贯的风格，提高代码编写的可读性和使用的一贯性。

1.2 范围

适用于嵌入式C开发人员。

1.3 总体原则

在程序开发的过程中应当遵循以下几条总体原则：

1)文件须根据工程的需要分类进行统一存放，集中管理。
2)文件的命名应与工程保持协调，并能表达其内容最强烈的意向。（参见附录1）
3)文档文件、程序文件应精简适当，并保持完整的一致性、实时性。
4)标识符的命名要清晰、明了、直观、准确，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。
5)程序块要采用缩进风格编写。
6)注释的内容要清楚、明了，含义准确，源程序有效注释量在20％以上。
7)对变量进行恰当命名，使它成为自描述性的，以提高代码可读性。
8)明确函数功能，精确（而不是近似）地实现函数设计,函数的功能应单一，不可包含多种功能。函数名能准确描述函数的功能。
9)函数的返回值要清楚、明了，让使用者不容易忽视错误情况。**说明：**函数的每种出错返回值的意义要清晰、明了、准确，防止使用者误用、理解错误或忽视错误返回码。
10)注意编写高效、简洁的代码。

2 文件

2.1 规范

1) 文件须根据工程的需要分类进行统一存放，集中管理。

文件可大体分为下列几类：

程序文件：公共库，项目私有库，项目源码
编译输出文件：编译中间文件，编译可执行文件
工程配置文件：Makefile,keil配置文件
文档文件：需求，项目设计，测试，集成，资料参考，项目总结，其他。

2) 用户编写代码文件名全部小写，包括头文件（.h）和源文件(.c)，汇编源文件(*.s)。

3) 头文件后缀为.h，源文件后缀为.c,汇编源文件后缀为.s，一个源码实现一个模块相关功能，不要包含其他无关代码。测试文件一律在命名中加_Test。

4) 对工程中常用到的结构、常量、全局变量声明等应单独存放为.h文件。

说明：对整个项目来说需要针对模块细分。每个模块常用到的结构、常量和变量存放为该模块的.h文件，整个项目常用到的结构、常量和变量应存放为项目公用的.h文件。公用的.h放在公共目录下，比如include目录下

5) 为了防止头文件被重复引用，应当用ifndef/define/endif结构产生预处理块。

6) 用 #include <filename.h> 格式来引用标准库的头文件（编译器将从标准库目录开始搜索）。

7) 用 #include "filename.h" 格式来引用非标准库的头文件（编译器将从用户的工作目录开始搜索）。

示例：

#ifndef  GRAPHICS_H      // 防止graphics.h被重复引用
#define GRAPHICS_H#include <math.h>           // 引用标准库的头文件
…
#include “myheader.h”   // 引用非标准库的头文件
…
void Function1(…);      // 全局函数声明
…
#endif

8) 头文件中只声明而不定义。

9) 在非特殊情况下文件统一使用utf-8字符集编码。

2.2 建议

不提倡使用全局变量，尽量不要在头文件中出现象extern int value 这类声明。

3 标识符命名

3.1 规范

1) 一个项目中命名规范必须保持一致，建议使用unix命名或者驼峰法命名

2) 变量的名字应当使用“名词”或者“形容词＋名词”。

示例,驼峰法：

float Value;
float OldValue;
float NewValue;

或者unix命名法：

float old_value;
Float new_value;

3) 函数的名字应当使用“动词”或者“动词＋名词”（动宾词组），

示例：

draw_box();
box->draw();

4) 命名中若使用特殊约定或缩写，则要有注释说明。

说明：对整个项目来说，应建立一个项目词汇表，统一管理出现的约定和缩写。

5) 尽量避免标识符中出现数字编号。

说明：有时为了计算或其他需要有数字编号的标识符，应加以详细说明。

示例：

如Value1,Value2等，除非逻辑上的确需要编号。

6) 程序中不要出现仅靠大小写区分的相似的标识符。

示例：

int  x,  X;      // 变量x 与 X 容易混淆。

7) 对于变量命名，禁止取单个字符（如i、j、k…），建议除了要有具体含义外，还能表明其变量类型、数据类型等，但i、j、k作局部循环变量是允许的。

说明：变量，尤其是局部变量，如果用单个字符表示，很容易敲错（如i写成j），而编译时又检查不出来，有可能为了这个小小的错误而花费大量的查错时间。

8) 函数的参数命名取更直接的名称。函数的参数建议在其名称后加_para,防止参数的偶然性被修改，也利于程序的阅读。

示例：

void setCurrent( int current_para )
{current  = current_para;     // 很清楚引用的是参数
}

9) 为了防止某一软件库中的一些标识符和其它软件库中的冲突，可以为各种标识符加上能反映软件性质的前缀。例如USB所有库函数均以usb开头，所有常量（或宏定义）均以USB开头。（缩小为模块）

3.2 建议

标识符采用英文单词或其组合，切忌使用汉语拼音来命名，用词应当准确。

例如不要把CurrentValue写成NowValue。较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。

示例：如下单词的缩写能够被大家基本认可。

temp      可缩写为  tmp ;        maximal      可缩写为  max ;
flag      可缩写为  flg ;        minimum      可缩写为  min ;
statistic 可缩写为  stat;        length       可缩写为  len ;
increment 可缩写为  inc ;        remove       可缩写为  rm  ;
message   可缩写为  msg ;        delete       可缩写为  del ;
dynamic   可缩写为  dyna;        rectangle    可缩写为  rect;
windows   可缩写为  win ;        dialog       可缩写为  dlg ;
image     可缩写为  img ;        network      可缩写为  net ;
transfers 可缩写为  trans;       capacitance  可缩写为  capc ;
parameter 可缩写为  para;        source       可缩写为  src

11) 用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

说明：下面是一些在软件中常用的反义词组。

add / remove       begin / end        create / destroy
insert / delete    first / last       get / release
increment / decrement                 put / get
add / delete       lock / unlock      open / close
min / max          old / new          start / stop
next / previous    source / target    show / hide
send / receive     source / destination
cut / paste        up / down

示例：

int  min_sum;
int  max_sum;
int  add_user( BYTE *user_name );
int  delete_user( BYTE *user_name );

12) 除了编译开关/头文件等特殊应用，应避免使用EXAMPLE_TEST之类以下划线"_"线开始和结尾的定义。

4 可读性

4.2 规范

1) 程序块要采用缩进风格编写，缩进为一个TAB键（TAB键设为4个空格字符）。

2) 较长的语句（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读；划分后的上一行末尾可用续行符 “\”与下一行保持良好的连续性。

示例1：

strcpy( msg, "###################################\######################" );

示例2：

perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN+ STAT_SIZE_PER_FRAM * sizeof( _UL );act_task_table[frame_id * STAT_TASK_CHECK_NUMBER + index].occupied= stat_poi[index].occupied;act_task_table[taskno].duration_true_or_false= SYS_get_sccp_statistic_state( stat_item );report_or_not_flag = ( ( taskno < MAX_ACT_TASK_NUMBER )&& ( n7stat_stat_item_valid ( stat_item ) )&& ( act_task_table[taskno].result_data != 0 ) );

3) 循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低优先级操作符处划分新行，操作符放在新行之首。

示例：

if ( ( taskno < max_act_task_number )&& ( n7stat_stat_item_valid ( stat_item ) ) )
{... // program code
}for ( i = 0, j = 0; ( i < BufferKeyword[word_index].word_length )&& ( j < NewKeyword.word_length ); i++, j++ )
{... // program code
}for ( i = 0, j = 0;  ( i < first_word_length ) && ( j < second_word_length );  i++, j++ )
{... // program code
}

4) 若函数或过程中的参数较长，则要进行适当的划分。

示例：

n7stat_str_compare( ( BYTE * ) & stat_object,( BYTE * )  & ( act_task_table[taskno].stat_object ),sizeof( _STAT_OBJECT ) );n7stat_flash_act_duration( stat_item, frame_id *STAT_TASK_CHECK_NUMBER+ index, stat_object );

5) 不允许把多个短语句写在一行中，即一行只写一条语句。

示例：如下例子不符合规范。

rect.length = 0;  rect.width = 0;

应如下书写

rect.length = 0;
rect.width  = 0;

6) if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while、case等语句的执行语句部分无论多少都要加括号{}。

示例1：如下例子不符合规范。

if ( pUserCR == 0 ) return;if( pUserCR == 1 ){ return;
}
else if ( pLeaderCR == 2 )
{pUserCR = 0;
}

应如下书写：

if ( 0 == pUserCR )
{return;
}if( pUserCR == 1 )
{ return;
} else if ( pLeaderCR == 2 )  {  // else if 独占一行pUserCR = 0;
}

示例2：如下例子不符合规范。

int i;
switch ( i )
{
case 0:
//...
break;
case 1:
//...
break;
default:
break;
}

应如下书写：

int i;
switch ( i )
{case 0:{break;}case 1:{break;}default:{break;}
}

7) 在switch语句中不要忘记最后那个default分支。即使程序真的不需要default处理，也应该保留语句 default : break; 这样做并非多此一举，而是为了防止别人误以为你忘了default处理。

8) 函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case语句下的情况处理语句也要遵从语句缩进要求。

9) 在函数实现、类的定义、结构定义、枚举的定义以及if 、for、do、while、switch语句中的代码，要求’{‘和’}’各独占一行并且位于第一列，并与引用它们的语句左对齐，代码语句一般情况下要求采用缩进方式。

示例：如下例子不符合规范：

void example_fun( void ){... // program code}

应如下书写：

void example_fun( void )
{... // program code
}

示例：如下例子不符合规范。

for (...) {... // program code
}if (...) {... // program code}

应如下书写。

for (...)
{... // program code
}

10) 在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如－>、.），后不应加空格。

说明： 采用这种松散方式编写代码的目的是使代码更加清晰。

由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加空格，因为在C/C++语言中括号已经是最清晰的标志了。

在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。给操作符留空格时不要连续留两个以上空格。

示例：

(1) 逗号、分号只在后面加空格。

int a, b, c;

(2) 比较操作符, 赋值操作符"="、 “+=”，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格。

if ( current_time >= MAX_TIME_VALUE )
a = b + c;
a *= 2;
a = b ^ 2;

(3) “!”、"~"、"++"、"–"、"&"（地址运算符）等单目操作符前后不加空格。

*p = 'a';        // 内容操作"*"与内容之间
flag = !isEmpty; // 非操作"!"与内容之间
p = &mem;        // 地址操作"&" 与内容之间
i++;             // "++","--"与内容之间

(4) “->”、"."、"->"、"."前后不加空格。

p->id = pid;     // "->"指针前后不加空格

(5) if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。C关键字一般都要加空格,以突出关键字，也利于阅读和维护。

if ( a >= b && c > d )

(6) 左括号"（“后、右括号”）"前必须加空格。

11) 在每个函数定义结束之后都要加空行。

12) 源程序中逻揖上密切相关的语句尽可能相邻，并以空行与其他行相隔离。

示例：

while ( condition )
{statement1;// 空行if ( condition ) {statement2;}  else  {statement3;}// 空行statement4;
}

示例：以下代码布局不太合理。

rect.length  = 10;
char_poi     = str;
rect.width   = 5;

若按如下形式书写，可能更清晰一些。

rect.length  = 10;
rect.width   = 5; // 矩形的长与宽关系较密切，放在一起。char_poi     = str;

13) 注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。

说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。

示例：下列语句中的表达式

word = (high << 8) | low        (1)
if( ( a | b ) && ( a & c ) )    (2)
if( ( a | b ) < ( c & d ) )     (3)

如果书写为:

word = high << 8 | low     (1)
if ( a | b && a & c )      (2)
if ( a | b < c & d )       (3)

由于:

high << 8 | low 等同于 ( high << 8 ) | low,

a | b && a & c 等同于 ( a | b ) && ( a & c )，

(1)(2)不会出错，但语句不易理解；

a | b < c & d 运算逻辑等同于 a | ( b < c ) & d，(3)造成了判断条件出错。

14) 避免用不易理解的数字在跨函数或文件中使用，用有意义的标识来替代。

示例：如下的程序可读性差。

void function_test1( void )
{if ( Trunk[index].trunk_state == 0 ){Trunk[index].trunk_state = 1;...  // program code}
}void function_test2( void )
{if ( Trunk[index].trunk_state == 0 ){Trunk[index].trunk_state = 1;...  // program code}
}

应改为如下形式:

const int TRUNK_IDLE = 0;
const int TRUNK_BUSY = 1;if ( TRUNK_IDLE == Trunk[index].trunk_state )
{Trunk[index].trunk_state = TRUNK_BUSY;...  // program code
}void function_test1( void )
{if ( TRUNK_IDLE == Trunk[index].trunk_state ){Trunk[index].trunk_state = TRUNK_BUSY;...  // program code}
}void function_test2( void )
{if ( TRUNK_IDLE == Trunk[index].trunk_state ){Trunk[index].trunk_state = TRUNK_BUSY;...  // program code}
}

15) 不要编写太复杂的复合表达式。

示例：

i = a >= b && c < d && c + f <= g + h ;    // 复合表达式过于复杂

16) 不要有多用途的复合表达式。

示例：

d = ( a = b + c ) + r ;

该表达式既求a值又求d值。应该拆分为两个独立的语句：

a = b + c;
d = a + r;

4.3 建议

17) 一行程序以小于80字符为宜，不要写得过长。

18) 不要吝啬空行，应尽量利用空行来提高程序的可读性。

19) 不要使用难懂的技巧性很高的语句，除非很有必要时。

说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。

示例：如下表达式，考虑不周就可能出问题，也较难理解。

    * stat_poi ++ += 1;* ++ stat_poi += 1;

应分别改为如下。

    *stat_poi += 1;stat_poi++;     // 此二语句功能相当于“ * stat_poi ++ += 1; ”++ stat_poi;*stat_poi += 1;   // 此二语句功能相当于“ * ++ stat_poi += 1; ”

20) 尽量少用嵌套调用，多次调用时应当使用过渡形式。

5 注释

5.1 规范

1) 统一使用doxygen注释格式, 命令格式为 @+命令符号，例如标记作者：@author。

2) 代码注释(不用导出到生成文档中)以//开始，要求随后必须空一格；

示例1：

int  sn = 0;        // 序号

3) 避免在注释中使用缩写，特别是非常用缩写。

说明：在使用缩写时或之前，应对缩写进行必要的说明。

4) 注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。

示例：如下例子不符合规范。

例1：

// get replicate sub system index and net indicator repssn_ind  = ssn_data[index].repssn_index;
repssn_ni   = ssn_data[index].ni;

例2：

repssn_ind = ssn_data[index].repssn_index;
repssn_ni  = ssn_data[index].ni;
// get replicate sub system index and net indicator

应如下书写

// get replicate sub system index and net indicator
repssn_ind = ssn_data[index].repssn_index;
repssn_ni  = ssn_data[index].ni;

例3：

// get replicate sub system index and net indicator
repssn_ind = ssn_data[index].repssn_index;
repssn_ni  = ssn_data[index].ni;
// end

应如下书写

/
// get replicate sub system index and net indicator
repssn_ind = ssn_data[index].repssn_index;
repssn_ni  = ssn_data[index].ni; // end

5) 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

6) 注释与所描述内容进行同样的缩排。

说明：可使程序排版整齐，并方便注释的阅读与理解。

示例：如下例子，排版不整齐，阅读稍感不方便。

void example_fun( void )
{
// code one comments CodeBlock One// code two comments CodeBlock Two
}

应改为如下布局:

void example_fun( void )
{// code one comments CodeBlock One// code two comments CodeBlock Two
}

7) 将注释与其上面的代码用空行隔开。

示例：如下例子，显得代码过于紧凑。

// code one comments
program code one
// code two comments
program code two

应如下书写

// code one comments
program code one// code two comments
program code two

8) 在编写临时用的测试代码时应加必要的注释，以利于将来的维护。

示例：

int  i = strcmp( dest_para, source_para );   // i 为测试代码；

9) 源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。

/*** @file        文件名* @author      作者  * @version     版本号* @date        编写日期 * @brief       文件描述* @copyright   版权描述* @attention   注意事项        */#include <string.h>

说明：@brief一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。

10) 函数声明处头部应进行注释，列出：函数的目的、功能、输入参数、输出参数、返回值。

示例：

/*** @brief           函数描述    * @param[in|out]   arg    函数参数arg描述* @return          返回值描述*/int caculate( int arg );

11) 全局变量命名不是充分自注释的，必须加以注释。全局变量要有较详细的注释，包括对其功能、取值范围以及存取时注意事项等的说明。全局变量的注释根据注释的长度有两种注释格式，注意：局部变量无需“//!<”这种格式，使用“//”格式即可。

(1) 注释长度和变量总长度大于80个字符使用以下示例格式注释：

/*** 变量描述   */
int i = 4;

(2) 注释长度和变量总长度小于80个字符使用以下示例格式注释：

int i = 4; //!<  变量描述

12) 数据结构声明(包括数组、结构、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面。

示例：

/*** 枚举描述*/
enum  SCCP_USER_PRIMITIVE
{N_UNITDATA_IND,    //!< 单行成员注释，格式同变量注释格式N_NOTICE_IND,    //!< 单行成员注释格式/***  多行成员注释格式，格式同变量注释格式*  第二行，格式同变量注释格式*/N_UNITDATA_REQ,
};

13) 对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。

示例：

int Temperature; // 温度
if ( Temperature > 100 )        // 水开了
{flag = flase                 // 控制循环的变量for ( ; ; ;){ if ( true == flag ){break;}}
} else if ( Temperature > 36 ) { // 水比人体温度高} else if ( Temperature > 0 ) {  // 水在结冰的临界状态} else { // 零下状态}

14) 对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。

说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。

示例：（注意斜体加粗部分）

case CMD_UP:
{  ProcessUp(); break;
}case CMD_DOWN:
{ProcessDown(); break;
}case CMD_FWD:
{  ProcessFwd(); if (...) {...break;} else {ProcessCFW_B();   // now jump into case CMD_A}
}
case CMD_A:
{    ProcessA();    break;
}
case CMD_B:
{    ProcessB();    break;
}case CMD_C:
{ProcessC();    break;
}case CMD_D:
{ProcessD();    break;
}
...

15) 当代码段较长，特别是多重嵌套时在程序块的结束行右方加注释标记，以表明某程序块的结束。

说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。

示例：参见如下例子。

if (...)
{// program codewhile ( index < MAX_INDEX ) {// program code} // end of while (index < MAX_INDEX) // 指明该条while语句//结束
} // end of  if (...) // 指明是哪条if语句结束

5.2 建议

16) 避免在一行代码或表达式的中间插入注释。

说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。

17) 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。

说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

18) 在代码的功能、意图层次上进行注释，提供有用、额外的信息。

说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。

示例：如下注释意义不大。

// if receive_flag is TRUE
if ( receive_flag )

而如下的注释则给出了额外有用的信息:

// if mtp receive a message from links
if ( receive_flag )

6 变量、常量和结构

6.1 规范

1) 不允许把变量集中一块定义，而是需要时才定义。且不可在同一行定义多个变量或常量。

示例：不符合规范。

char  *name, k;
int   *x, y;

应如下书写：

char* name;
char  k;
int*  x;
int   y;

2) 应当将修饰符 * 和＆紧靠类型。

示例：

char*  name;

3) 整型变量用== 与常整形数据比较，常整型数据在==符号左侧，整形变量在右侧。

说明：规避将==写成 =，而编译器检测不出错误导致留下潜在bug，而遵照此规范编写可杜绝此类问题出现

示例：

if ( value == 1 )

应该写成：

if ( 1 == value )

5) 不可将浮点变量用==或!=与任何数字比较。

说明：千万要留意，无论是float还是double类型的变量，都有精度限制。所以一定要避免将浮点变量用==或!=与数字比较，应该设法转化成>=或<=形式。

6) 不可在for 循环体内修改循环变量，防止for 循环失去控制。

7) 如果某一常量与其它常量密切相关，应在定义中包含这种关系，而不应给出一些孤立的值。

示例：

const  float   RADIUS   = 100;
const  float   DIAMETER = RADIUS * 2;

8) 避免数组或指针的下标越界，特别要当心发生“多1”或者“少1”操作。

9) 尽量减少没有必要的数据类型默认转换与强制转换。

6.2 建议

10) 使用严格形式定义的、可移植的数据类型，尽量不要使用与具体硬件或软件环境关系密切的变量。

说明：使用标准的数据类型，有利于程序的移植。

11) 合理地设计数据并使用自定义数据类型，避免数据间进行不必要的类型转换。

12) 对自定义数据类型进行恰当命名，使它成为自描述性的，以提高代码可读性。注意其命名方式在同一产品中的统一。

说明：使用自定义类型，可以弥补编程语言提供类型少、信息量不足的缺点，并能使程序清晰、简洁。

示例：可参考如下方式声明自定义数据类型。

下面的声明可使数据类型的使用简洁、明了。

typedef unsigned char  BYTE;
typedef unsigned short WORD;
typedef unsigned int   DWORD;

下面的声明可使数据类型具有更丰富的含义。

typedef float DISTANCE;
typedef float SCORE;

15) 尽可能在定义变量的同时初始化该变量（就近原则）。

说明：如果变量的引用处和其定义处相隔比较远，变量的初始化很容易被忘记。如果引用了未被初始化的变量，可能会导致程序错误。本建议可以减少隐患。

示例：

void main(void)
{int width  = 10;  // 定义并初绐化width int height = 10;    // 定义并初绐化height int depth  = 10;   // 定义并初绐化depth....
}

7 函数

7.1 规范

1) 参数命名要恰当，顺序要合理。参数的书写要完整，不要贪图省事只写参数的类型而省略参数名字。如果函数没有参数，则用void填充。

示例：

void setValue( int width_para, int height_para );    // 良好的风格
void setValue( int, int );              // 不良的风格
float getValue( void );     // 良好的风格
float getValue( );          // 不良的风格

2) 如果参数是指针，且仅作输入用，则应在类型前加const，以防止该指针在函数体内被意外修改。

示例：

void StringCopy( char *strDestination，const char *strSource );

3) 避免函数有太多的参数，参数个数尽量控制在5个以内。如果参数太多，在使用时容易将参数类型或顺序搞错。

4) 对所调用函数的错误返回码要仔细、全面地处理。

5) 不要省略返回值的类型。如果函数没有返回值，那么应声明为void类型。

6) 函数名字与返回值类型在语义上不可冲突。

说明：违反这条规则的典型代表是C标准库函数getchar。

示例：

char c;
c = getchar();
if ( c == EOF )
…

按照getchar名字的意思，将变量c声明为char类型是很自然的事情。但不幸的是getchar的确不是char类型，而是int类型，其原型如下：

    int getchar( void );

由于c是char类型，取值范围是[-128，127]，如果宏EOF的值在char的取值范围之外，那么if语句将总是失败，这种“危险”人们一般哪里料得到！导致本例错误的责任并不在用户，是函数getchar误导了使用者。

7) 在函数体的“入口处”，对参数的有效性进行检查。在函数体的“出口处”，对return语句的正确性和效率进行检查。

8) return语句不可返回指向“栈内存”的“指针”，因为该内存在函数体结束时被自动销毁。

示例：

char * Func( void )
{char str[] = “hello world”;   // str的内存位于栈上…return str;       // 将导致错误
}

7.2 建议

9) 防止将函数的参数作为工作变量。

说明：将函数的参数作为工作变量，有可能错误地改变参数内容，所以很危险。对必须改变的参数，最好先用局部变量代之，最后再将该局部变量的内容赋给该参数。

示例：下函数的实现不太好。

void sum_data( unsigned int num, int* data, int* sum )
{unsigned int count;*sum = 0;for ( count = 0; count < num; count++ ) {*sum  += data[count]; // sum成了工作变量，不太好。}
}

若改为如下，则更好些:

void sum_data( unsigned int num, int *data, int *sum )
{unsigned int count ;int sum_temp;sum_temp = 0;for ( count = 0; count < num; count ++ ) {sum_temp  += data[count]; }*sum = sum_temp;
}

10) 函数的规模尽量限制在200行以内。

说明：不包括注释和空格行。

11) 检查函数所有参数输入的有效性。

12) 检查函数所有非参数输入的有效性，如数据文件、全局变量等。

说明：函数的输入主要有两种：一种是参数输入；另一种是全局变量、数据文件的输入，即非参数输入。函数在使用输入之前，应进行必要的检查。

13) 避免函数中不必要语句，防止程序中的垃圾代码。

说明：程序中的垃圾代码不仅占用额外的空间，而且还常常影响程序的功能与性能，很可能给程序的测试、维护等造成不必要的麻烦。

15) 防止把没有关联的语句放到一个函数中。

说明：防止函数或过程内出现随机内聚。随机内聚是指将没有关联或关联很弱的语句放到同一个函数或过程中。随机内聚给函数或过程的维护、测试及以后的升级等造成了不便，同时也使函数或过程的功能不明确。使用随机内聚函数，常常容易出现在一种应用场合需要改进此函数，而另一种应用场合又不允许这种改进，从而陷入困境。

在编程时，经常遇到在不同函数中使用相同的代码，许多开发人员都愿把这些代码提出来，并构成一个新函数。若这些代码关联较大并且是完成一个功能的，那么这种构造是合理的，否则这种构造将产生随机内聚的函数。

示例：如下函数就是一种随机内聚。

void init_var( void )
{rect.length = 0;rect.width  = 0; // 初始化矩形的长与宽 point.x = 10;point.y = 10;    // 初始化“点”的坐标
}

矩形的长、宽与点的坐标基本没有任何关系，故以上函数是随机内聚。

应如下分为两个函数：

void init_rect( void )
{rect.length = 0;rect.width  = 0; // 初始化矩形的长与宽
}void init_point( void )
{point.x = 10;point.y = 10;   // 初始化“点”的坐标
}

8 附注

8.1 规则

1) 在多重循环中，如果有可能，应当将最长的循环放在最内层，最短的循环放在最外层，以减少CPU跨切循环层的次数。

示例：不符合规范；

for ( row = 0; row < 100; row++ )
{for ( col = 0; col < 5; col++ ) {sum = sum + a[row][col];}
}

应如下书写：

for ( col = 0; col < 5; col++ )
{for ( row = 0; row < 100; row++ ){sum = sum + a[row][col];}
}

2) 如果循环体内存在逻辑判断，并且循环次数很大，宜将逻辑判断移到循环体的外面。

说明：如下示例a的程序比示例b多执行了N-1次逻辑判断。并且由于前者老要进行逻辑判断，打断了循环“流水线”作业，使得编译器不能对循环进行优化处理，降低了效率。如果N非常大，最好采用示例b的写法，可以提高效率。如果N非常小，两者效率差别并不明显，采用示例a的写法比较好，因为程序更加简洁。

示例a：效率低但程序简洁

for ( i = 0; i < N; i++ )
{if ( condition ){DoSomething();} else {DoOtherthing();}
}

示例b：效率高但程序不简洁

if ( condition )
{for ( i = 0; i < N; i++ ){DoSomething();}
} else {for ( i = 0; i < N; i++ ){DoOtherthing();}
}

9 附录

9.1 附录1：文件命名规范要求示例

1) 界面窗体类

前缀：winmain

例如：

单线程图形主窗口：winmain_singleline.h, winmain_singleline.c

地理位置界线图程序窗口：winmain_geo.h, winmain_geo.c

2) 对话框类

前缀：windlg

例如：

选项对话框：windlg_option.h, windlg_option.c

3) 数据库类

前缀：db

例如:

设备日志数据库：db_device_log.db

4) 数据类

前缀: data

例如：

显示字体数据： data_font.h, data_font.c

5) 图形类：

前缀： img

例如：

剪切图标：imgcut.png

9.2 附录2：标识符命名规范要求示例

1) 变量、结构命名

常量 const: 一律大写，

例如：

缓冲区空间大小命名：BUFFERSIZE

最大长度命名：MAX_LENGTH

自定义类型：一律大写

例如：

距离类型：typedef float DISTANCE;

学分：typedef float SCORE;

2) 函数命名

全局函数 “动词”或者“动词＋名词”（动宾词组），

函数名:

void draw( void );
void setValue( int value_para );

函数的参数命名取更直接的名称，最好在其名称后加_para，

例如：

void set_value( int width_para, int height_para )
{// 很清楚引用的是参数m_width  = width_para;// 很清楚引用的是参数  m_height = height_para;
}

9.3 附录3：常用的单词缩写和反义词

下面是一些在软件中常用的反义词组。

add / remove       begin / end        create / destroy
insert / delete    first / last       get / set
increment / decrement                 put / get
add / delete       lock / unlock      open / close
min / max          old / new          start / stop
next / previous    source / target    show / hide
send / receive     source / destination
cut / paste        up / down

示例：

int  min_sum;
int  max_sum;
int  add_user( BYTE *user_name );
int  delete_user( BYTE *user_name );

下面是一些在软件中常用的缩写。

temp      可缩写为  tmp ;       maximal      可缩写为  max ;
minimum   可缩写为  min ;       rectangle    可缩写为  rect;
statistic 可缩写为  stat;       length       可缩写为  len ;
increment 可缩写为  inc ;       remove       可缩写为  rm  ;
message   可缩写为  msg ;       delete       可缩写为  del ;
windows   可缩写为  win ;       dialog       可缩写为  dlg ;
image     可缩写为  img ;       network      可缩写为  net ;
transfers 可缩写为  trans;      capacitance  可缩写为  capc ;
parameter 可缩写为  para;       source       可缩写为  src