嵌入式软件编程规范.doc

Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision: 0.9
Date: 2005-1-3
Process Owner: QA Team

Photonic Bridges 嵌入式软件编程规范

Rev.
Date
ECO
Originated by
History
0.9
2005-1-3

Yan An
根据12-28 QA Team Review整理，从“编程参考”中分离出一篇较为简短的“编程规范”。
将内部讨论得到的一篇短文《代码质量定义》加入成为第10章。
1.0
2005-1-13

Zhao zhengfu
根据2005-1-12的QA扩大会议的建议进行整理，增加了附录B。

1 文档概述 3
1.1 关于本文档 3
1.2 参考文献 3
2 排版 4
3 注释 9
4 标识符命名 17
5 可读性 23
6 变量、结构 24
7 宏 29
8 函数、过程 31
9 可测性 38
10 代码版本管理 41
10.1 代码质量定义 41
10.2 CVS分支定义 41
10.3 CVS代码引入规定 41
10.4 CVS代码Commit顺序 42
10.5 Commit文件过程中的其他注意事项 42
11 附录A – 推荐编辑器的默认配置修改 43
11.1 UntraEdit默认配置修改 43
11.2 Source-Insight默认配置修改 44
12 附录B– PC-LINT的使用简介 45
12.1 PC-LINT的软件包说明 45
12.2 PC-LINT的使用步骤 45
12.3 PC-LINT的使用规则(By FuJili) 46

1 文档概述
1.1 关于本文档
本文档规范了光桥科技（中国）有限公司嵌入式软件部软件代码的书写规范和原则。

本文档仅供公司内部员工使用。

公司机密，注意保密。

本文档中各规则的格式如下：
【规则 编号】 [规则内容] [[标记]]

其中[标记]的含义如下：
（必须） ： 表示该条规则是必须遵守的。
（建议） ： 表示该条规则是建议遵守的。
（可选）或没有标记 ： 表示该条规则是可选择遵守的。

本文档的示例中，如有使用“//”，并非代码注释，而是文档的注释(有可能是文档中对代码注释的解释)。

本文档是基于参考文献[9]－《编程参考》的简化版本，由于《编程参考》文档QA－TEAM不再进行维护，并且《编程参考》文档中相关的编程思想和技巧有一定参考价值，建议新员工在使用本文档之前以及进入工程研发之前先通读《编程参考》。
1.2 参考文献
[1] SW-00-00-0002-CodingConvention by YanAn(Ryan)
[2] SW-00-00-0090(DBG Guide).doc by YanAn(Ryan)
[3] SW-09-03-0190-Debug and release.doc by Huang Hairong
[4]高质量C++编程
[5]Effective C++
[6]More Effective C++
[7]C++ Primer
[8]Thinking in C++
[9]SW-00-00-0003-嵌入式软件编程参考
[10]PC-LINT 在PB项目管理中的应用（中文版） by zhao zhengfu

2 排版
l 【规则 21】程序块要采用缩进风格编写，缩进的空格数为4个,对齐使用空格键，不得使用TAB键。[必须]
嵌入式软件开发的代码编辑器，推荐使用Source Insight 和Ultra EDIT，编辑器参数设置见附录A。
l 【规则 22】相对独立的程序块之间、变量说明之后必须加空行。[必须]
示例：
不正确的书写方式：
if (!rpr_valid_ni(ni))
{
... // program code
}
gRprRepssnInd
= gRprSsnData[idx].repssn_index;
gRprRepssnNi = gRprSsnData[idx].ni;

正确的书写方式:
if (!rpr_valid_ni(ni))
{
... // program code
}

gRprRepssnInd
= gRprSsnData[idx].repssn_index;
gRprRepssnNi = gRprSsnData[idx].ni;

l 【规则 23】较长的语句（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。[必须]
示例：
gRprPermCountMsg.head.len = RPR_NO7_TO_STAT_PERM_COUNT_LEN +
RPR_STAT_SIZE_PER_FRAM * sizeof( UINT32 );

gSysAcbTaskTable[frame_id * RPR_STAT_TASK_CHECK_NUMBER + index].nOccupied =
rprStatPoi[index].nOccupied;

gSysAcbTaskTable[taskno].nDurationTrueOrFalse =
SYS_getSccpStatisticState( statItem );

gRprReportOrNotFlag = ((SYS_MAX_ACT_TASK_NUMBER > taskno) &&
(SYS_n7statStatItemValid (statItem)) &&
(0 != gSYSActTaskTable[taskno].resultData));

l 【规则 24】循环、判断等语句中若有较长的表达式或语句，则要进行适当的分行，长表达式要在低优先级操作符处划分新行，操作符放在行尾。[必须]
示例：
if ((taskno < gSysMaxActTaskNumber) &&
(SYS_n7statStatItemValid (statItem)))
{
... // program code
}
//空行
for (i = 0, j = 0;
(i < rprBufferKeyword[wordIndex].nWordLength) &&
(j < rprNewKeyword.nWordLength); i++, j++)
{
... // program code
}
//空行
for (i = 0, j = 0;
(i < rprFirstWordLength) && (j < rprSecondWordLength);
i++, j++)
{
... // program code
}

l 【规则 25】若函数的参数较长，则要进行适当的分行。[必须]
示例：
rpr_n7statStrCompare((UINT8 *) & statObject,
(UINT8 *) & (gSysActTaskTable[taskno].statObject),
sizeof (SYS_STAT_OBJECT));

rpr_n7statFlashActDuration( statItem, frameId * SYS_STAT_TASK_CHECK_NUMBER
+ index, statObject );

l 【规则 26】不允许把多个短语句写在一行中，即一行只写一条语句。[必须]
示例：
不正确的书写方式：
rect.nLength = 0; rect.nWidth = 0;

正确的书写方式：
rect.nLength = 0;
rect.nWidth = 0;

l 【规则 27】if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。[必须]
示例：
不正确的书写方式：
if (pUserCR == NULL) return;

正确的书写方式：
if (NULL == pUserCR)
{
return;
}

l 【规则 28】在比较表达式中，如果有常量，尽量把常量放在前面。[建议]
这样，万一不小心把“==”误敲成“=”，就会通不过翻译，不致引起难查的问题。
l 【规则 29】程序块的分界符（如C/C++语言的大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。[建议]
示例：本规则的特例见2－7的说明部分。
不正确的书写方式：
for (...) {
... // program code
}

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

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

正确的书写方式：
for (...)
{
... // program code
}

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

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

switch(var)
{
case OPTION1:
break;

case OPTION2:
if (CONDITION < a)
{
/* code */
}
break;
default:
break;
}

l 【规则 210在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如－>），后不应加空格。[必须]
说明：采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加空格，因为在C/C++语言中括号已经是最清晰的标志了。
在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。给操作符留空格时不要连续留两个以上空格。

示例：
【规则 210-1】 逗号、分号只在后面加空格。
int a, b, c;

【规则 210-2】比较操作符, 赋值操作符"="、 "+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格。
if (currentTime >= MAX_TIME_VALUE)
a = b + c;
a *= 2;
a = b ^ 2;

【规则 210-3】"!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。
*p = 'a'; // 内容操作"*"与内容之间
flag = !isEmpty; // 非操作"!"与内容之间
p = &mem; // 地址操作"&" 与内容之间
i++; // "++","--"与内容之间

【规则 210-4】"->"、"."前后不加空格。
p->id = pid; // "->"指针前后不加空格

【规则 210-5】if、for、while、switch等与后面的括号间应加空格，使if等关键字更为突出、明显。
if ((a >= b) && (c > d))

3 注释
l 【规则 31】一般情况下，源程序有效注释量必须在20％以上(建议20-30%)。[必须]
说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁。
l 【规则 32】C代码不得使用C++的注释语法“//”，必须使用/*….*/。[必须]
注：本文档的示例中，如有使用“//”，并非代码注释，而是文档的注释(有可能是文档中对代码注释的解释)。
l 【规则 33】说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应进行注释，注释必须列出：版权说明、模块名、文件名、作者、内容介绍、修改日志等，头文件的注释中还应有函数功能简要说明。[必须]
头文件模板示例：
/***********
*
* (c) Copyright 2001-2005, Photonic Bridges, All Rights Reserved.
* THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF PHOTONIC BRIDGES, INC.
* The copyright notice above does not evidence any actual or intended
* publication of such source code.
*
* Subsystem: XXX
* File: XXX_ei.h
* Author: Xxx
* Description: Template for C header files.
*
* //其它在头文件可选择的包括的内容
* Others: // 其它内容的说明
* Function List: // 主要函数列表，每个函数一行，包含其返回值类型及参数类型。功能说明应当放在函数头注释中
* 1. ....
* History: // 修改历史记录列表，每条修改记录应包括修改日期、修改
* // 者及修改内容简述。(参见底注)
* 1. Date:
* Author:
* Modification:
* 2. ...
*
*********************************************************************/

#ifndef _FILENAME_H
#define _FILENAME_H

//program code

#endif /* _FILENAME_H */

/*
* $Id$
* $Log$
*
*/

【规则 33-1】注：文件末尾的代码用于CVS自动生成修改记录。注意在commit代码时使用正确的MR，并填写充分、准确的注释，这个修改记录是很好用的。所以一般不需要在文件头手工记录修改历史；通常建议只有对模块进行大规模的、结构性的改动才需要手工记录修改历史。[必须]
【规则 33-2】为了防止头文件被重复引用，应当用#ifndef/#define/#endif结构产生预处理块。[必须]
【规则 33-3】用 #include h> 格式来引用标准库的头文件（编译器将从标准库目录开始搜索）。[必须]
【规则 33-4】用 #include “filename.h” 格式来引用非标准库的头文件（编译器将从用户的工作目录开始搜索）。[必须]
【规则 33-5】头文件中只存放“声明”而不存放“定义”。(在C++ 语法中，类的成员函数可以在声明的同时被定义，并且自动成为内联函数。这虽然会带来书写上的方便，但却造成了风格不一致，弊大于利。建议将成员函数的定义与声明分开，不论该函数体有多么小。)[建议]

l 【规则 34】源文件头部应进行注释，列出：版权说明、版本号、作者、模块目的/功能、主要函数及其功能、修改日志等。[必须]
源文件模板示例：
/******************************************************************
* (c) Copyright 2001-2005, Photonic Bridges, All Rights Reserved.
* THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF PHOTONIC BRIDGES, INC.
* The copyright notice above does not evidence any actual or intended
* publication of such source code.
*
* Subsystem: XXX
* File: XXX_config.c
* Author: Xxxxx
* Description: Template for C source files.
*
* //可选择的增加部分内容
* Function List: //主要函数列表，每个函数一行，包含其返回值类型及参数类型。功能说明应当放在函数头注释中
* 1. ....
* History: // 修改历史记录列表，每条修改记录应包括修改日期、修改
* // 者及修改内容简述。(参见底注)
* 1. Date:
* Author:
* Modification:
* 2. ...
*
***************************************************************/
/*说明：Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系等。History是修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述。*/

#include "xxxxxx.h"

/********************************************************************
*
* Function Name: XXX_Func1
* Input: Param1 - meaning;
* Param2 - meaning;
* Output: If there's no parameters for output, this field can be
* "None" or omitted.
* Returns: OK,ERROR
* Description: This is an external function of XXX.
*
**********************************************************************/

STATUS XXX_Func1(UINT8 Param1, UINT32 Param2)
{
}

/*
* $Id$
* $Log$
*
*/

【规则 34-1】注：文件末尾的代码用于CVS自动生成修改记录。注意在commit代码时使用正确的MR，并填写充分、准确的注释，这个修改记录是很好用的。所以一般不需要在文件头手工记录修改历史；通常建议只有对模块进行大规模的、结构性的改动才需要手工记录修改历史。[必须]

l 【规则 35】函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系（函数、表）等。[必须]
函数注释模板示例：
/****************************************************************************
*
* Function Name: XXX_ExternalFunc1
* Input: Param1 - meaning;
* Param2 - meaning;
* Output: If there's no parameters for output, this field can be
* "None" or omitted.
* Returns: OK,ERROR
* Description: Performs xxx functions.
* Note: Any special note. This can be omitted.
*
* //其它可选择的函数头说明
* Calls: // 被本函数调用的函数清单
* Called By: // 调用本函数的函数清单
* Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）
* Table Updated: // 被修改的表（此项仅对于牵扯到数据库操作的程序）
* Others: // 其它说明
*
****/
STATUS XXX_ExternalFunc1(UINT8 Param1, UINT32 Param2);

【规则 35-1】外部函数必须有函数头注释。[必须]
【规则 35-2】内部函数强烈建议使用函数头注释。[建议]
l 【规则 36】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。注释的格式尽量统一。 [必须]
示例：
单行注释
/* Create a one shot timer, from now. */

多行注释
/* One or more tables of lteDevDescr structures must also be defined for each
board type into the dynamically-loaded board-specific configuration file.
The device descriptor provides function pointers that give standard
line termination equipment API access to a specific hardware driver. */

l 【规则 37】注释的内容要清楚、明了，含义准确，防止注释二义性。[建议]
说明：错误的注释不但无益反而有害。

l 【规则 38】避免在注释中使用缩写，特别是非常用缩写。[建议]
说明：在使用缩写时或之前，应对缩写进行必要的说明。
l 【规则 39】注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，不可放在下面；如放于上方则需与其上面的代码用空行隔开。[必须]
示例：如下例子不符合规范。
例1(错)：
/* get replicate sub system index and net indicator */

rprRepssnInd = rprSsnData[index].nRepssnIndex;
rprRepssnNi = rprSsnData[index].ni;

例2(错)：
rprRepssnInd = rprSsnData[index].nRepssnIndex;
rprRepssnNi = rprSsnData[index].ni;
/* get replicate sub system index and net indicator */

应如下书写
/* get replicate sub system index and net indicator */
rprRepssnInd = rprSsnData[index].nRepssnIndex;
rprRepssnNi = rprSsnData[index].ni;

l 【规则 310】对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。[必须]
示例：
示例1：
/* active statistic task number */
#define SYS_MAX_ACT_TASK_NUMBER 1000

示例2：
#define SYS_MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */

l 【规则 311】数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。[必须]
示例：可按如下形式说明枚举/数据/联合结构。
/* sccp interface with sccp user primitive message name */
typedef enum SCP_USER_PRIMITIVE_t
{
SCP_UNITDATA_IND, /* sccp notify sccp user unit data come */
SCP_NOTICE_IND, /* Sccp notify user the No.7 network can not
transmission this message */
SCP_UNITDATA_REQ, /* sccp user's unit data transmission request*/
} SCP_USER_PRIMITIVE_T;

l 【规则 312】全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明。[必须]
示例：
/* The ErrorCode when SCCP translate
Global Title failure, as follows
0 － SUCCESS
1 － GT Table error
2 － GT error
Others － not used
Only function SCCP_Translate() in
this modual can modify it, and other
module can visit it through call
the function SCCP_GetGTTransErrorCode() */
UINT8 gGTTranErrorCode;

l 【规则 313】代码中的特殊处理，或者软件work around，必须加注释，注明为何要这样做。[必须]
说明：只有加了注释，以后的维护者才有可能明白前因后果。
l 【规则 314】注释与所描述内容进行同样的缩排。[必须]
说明：可使程序排版整齐，并方便注释的阅读与理解。
示例：如下例子，不正确的布局，排版不整齐，阅读稍感不方便。
不正确的布局：
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
}

l 【规则 315】将注释与其上面的代码用空行隔开。[必须]
示例：
如下例子，显得代码过于紧凑：
/* code one comments */
program code one
/* code two comments */
program code two

应如下书写：
/* code one comments */
program code one

/* code two comments */
program code two

l 【规则 316】对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。[建议]
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序
l 【规则 317】对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。[必须]
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。
示例（注意斜体加粗部分）：
case CMD_UP:
ProcessUp();
break;

case CMD_DOWN:
ProcessDown();
break;

case CMD_FWD:
ProcessFwd();
ProcessCFW_B(); /* now jump into case CMD_A */

case CMD_A:
ProcessA();
break;

case CMD_B:
ProcessB();
break;

default:
break;
...

l 【规则 318】避免在一行代码或表达式的中间插入注释。（S）
说明：除非必要（如PC-LINT的行禁止检查标记），不应在代码或表达中间插入注释，否则容易使代码可理解性变差。

l 【规则 319】通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释的。[建议]
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。

l 【规则 320】代码的功能、意图层次上进行注释，提供有用、额外的信息。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。
示例：
如下注释意义不大。
/* if receive_flag is TRUE */
if (receive_flag)
而如下的注释则给出了额外有用的信息。
/* if mtp receive a message from links */
if (receive_flag)

l 【规则 321】在程序块的结束行右方加注释标记，以表明某程序块的结束。[可选]
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。Source Insight可以自动显示这类信息。
示例：参见如下例子。
if (flag)
{
// program code

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

l 【规则 322】注释应考虑程序易读及外观排版的因素，嵌入式软件的注释必须全部使用英文。[必须]

4 标识符命名
l 【规则 41】标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解。[建议]
说明：较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。
示例：如下单词的缩写能够被大家基本认可。
temp 可缩写为 tmp ;
flag 可缩写为 flg ;
statistic 可缩写为 stat ;
increment 可缩写为 inc ;
message 可缩写为 msg ;
reserve 可缩写为 resv;
l 【规则 42】命名中若使用特殊约定或缩写，则要有注释说明。[必须]
说明：应该在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进行必要的注释说明。
l 【规则 43】自己特有的命名风格，要自始至终保持一致，不可来回变化。[建议]
说明：个人的命名风格，在符合所在项目组或产品组的命名规则的前提下，才可使用。（即命名规则中没有规定到的地方才可有个人命名风格）。
l 【规则