Photonic Bridges
Photonic Bridges 嵌入式软件编程规范
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 2 of 46
Rev. Date ECO# Originated by History
2005-1-3 Yan An 根据 12-28 QA Team Review 整
理，从“编程参考”中分离出一篇较
为简短的“编程规范”。
将内部讨论得到的一篇短文《代码
质量定义》加入成为第 10 章。
2005-1-13 Zhao zhengfu 根据 2005-1-12 的 QA 扩大会议的
建议进行整理，增加了附录 B。
1 文档概述 ............................................................................................................................................................................3
关于本文档 ................................................................................................................................................................3
参考文献 ....................................................................................................................................................................3
2 排版 ....................................................................................................................................................................................4
3 注释 ....................................................................................................................................................................................9
4 标识符命名 ......................................................................................................................................................................17
5 可读性 ..............................................................................................................................................................................23
6 变量、结构 ......................................................................................................................................................................24
7 宏 ......................................................................................................................................................................................29
8 函数、过程 ......................................................................................................................................................................31
9 可测性 ..............................................................................................................................................................................38
10 代码版本管理 ..............................................................................................................................................................41
代码质量定义 ......................................................................................................................................................41
CVS 分支定义 .........................................................................................................................................................41
CVS 代码引入规定 .................................................................................................................................................41
CVS 代码 COMMIT 顺序 ..........................................................................................................................................42
COMMIT 文件过程中的其他注意事项....................................................................................................................42
11 附录 A – 推荐编辑器的默认配置修改 ......................................................................................................................43
UNTRAEDIT 默认配置修改 ......................................................................................................................................43
SOURCE-INSIGHT 默认配置修改 ..............................................................................................................................44
12 附录 B– PC-LINT 的使用简介 ..................................................................................................................................45
PC-LINT 的软件包说明 ..........................................................................................................................................45
PC-LINT 的使用步骤 ..............................................................................................................................................45
PC-LINT 的使用规则(BY FUJILI) ...........................................................................................................................46
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 3 of 46
1 文档概述
关于本文档
本文档规范了光桥科技（中国）有限公司嵌入式软件部软件代码的书写规范和原则。
本文档仅供公司内部员工使用。
公司机密，注意保密。
本文档中各规则的格式如下：
【规则 编号】 [规则内容] [[标记]]
其中[标记]的含义如下：
（必须） ： 表示该条规则是必须遵守的。
（建议） ： 表示该条规则是建议遵守的。
（可选）或没有标记 ： 表示该条规则是可选择遵守的。
本文档的示例中，如有使用“//”，并非代码注释，而是文档的注释(有可能是文档中对代码注释的解释)。
本文档是基于参考文献[9]－《编程参考》的简化版本，由于《编程参考》文档 QA－TEAM 不再进行维
护，并且《编程参考》文档中相关的编程思想和技巧有一定参考价值，建议新员工在使用本文档之前以及
进入工程研发之前先通读《编程参考》。
参考文献
[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 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
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 4 of 46
2 排版
【规则 2-1】程序块要采用缩进风格编写，缩进的空格数为4个,对齐使用空格键，不得使用TAB键。[必
须]
嵌入式软件开发的代码编辑器，推荐使用 Source Insight 和 Ultra EDIT，编辑器参数设置见附录 A。
【规则 2-2】相对独立的程序块之间、变量说明之后必须加空行。[必须]
示例：
不正确的书写方式：
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;
【规则 2-3】较长的语句（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作
符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。[必须]
示例：
= 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));
【规则 2-4】循环、判断等语句中若有较长的表达式或语句，则要进行适当的分行，长表达式要在低优
先级操作符处划分新行，操作符放在行尾。[必须]
示例：
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 5 of 46
if ((taskno < gSysMaxActTaskNumber) &&
(SYS_n7statStatItemValid (statItem)))
{
... // program code
}
//空行
for (i = 0, j = 0;
(i < rprBufferKeyword[wordIndex].nWordLength) &&
(j < ); i++, j++)
{
... // program code
}
//空行
for (i = 0, j = 0;
(i < rprFirstWordLength) && (j < rprSecondWordLength);
i++, j++)
{
... // program code
}
【规则 2-5】若函数的参数较长，则要进行适当的分行。[必须]
示例：
rpr_n7statStrCompare((UINT8 *) & statObject,
(UINT8 *) & (gSysActTaskTable[taskno].statObject),
sizeof (SYS_STAT_OBJECT));
rpr_n7statFlashActDuration( statItem, frameId * SYS_STAT_TASK_CHECK_NUMBER
+ index, statObject );
【规则 2-6】不允许把多个短语句写在一行中，即一行只写一条语句。[必须]
示例：
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 6 of 46
不正确的书写方式：
= 0; = 0;
正确的书写方式：
= 0;
= 0;
【规则 2-7】if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句
的执行语句部分无论多少都要加括号{}。[必须]
示例：
不正确的书写方式：
if (pUserCR == NULL) return;
正确的书写方式：
if (NULL == pUserCR)
{
return;
}
【规则 2-8】在比较表达式中，如果有常量，尽量把常量放在前面。[建议]
这样，万一不小心把“==”误敲成“=”，就会通不过翻译，不致引起难查的问题。
【规则 2-9】程序块的分界符（如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)
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 7 of 46
{
case OPTION1:
break;
case OPTION2:
if (CONDITION < a)
{
/* code */
}
break;
default:
break;
}
【规则 2-10】在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前
后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如－>），后不应加空格。[必须]
说明：采用这种松散方式编写代码的目的是使代码更加清晰。
由于留空格所产生的清晰性是相对的，所以，在已经非常清晰的语句中没有必要再留空格，如果语句已足够
清晰则括号内侧(即左括号后面和右括号前面)不需要加空格，多重括号间不必加空格，因为在 C/C++语言中
括号已经是最清晰的标志了。
在长语句中，如果需要加的空格非常多，那么应该保持整体清晰，而在局部不加空格。给操作符留空格时不
要连续留两个以上空格。
示例：
【规则 2-10-1】 逗号、分号只在后面加空格。
int a, b, c;
【规则 2-10-2】比较操作符, 赋值操作符"="、 "+="，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操
作符"<<"、"^"等双目操作符的前后加空格。
if (currentTime >= MAX_TIME_VALUE)
a = b + c;
a *= 2;
a = b ^ 2;
【规则 2-10-3】"!"、"~"、"++"、"--"、"&"（地址运算符）等单目操作符前后不加空格。
*p = 'a'; // 内容操作"*"与内容之间
flag = !isEmpty; // 非操作"!"与内容之间
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 8 of 46
p = &mem; // 地址操作"&" 与内容之间
i++; // "++","--"与内容之间
【规则 2-10-4】"->"、"."前后不加空格。
p->id = pid; // "->"指针前后不加空格
【规则 2-10-5】if、for、while、switch 等与后面的括号间应加空格，使 if 等关键字更为突出、明显。
if ((a >= b) && (c > d))
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 9 of 46
3 注释
【规则 3-1】一般情况下，源程序有效注释量必须在20％以上(建议20-30%)。[必须]
说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加了，注释不宜太多也不能太少，注释语言
必须准确、易懂、简洁。
【规则 3-2】C代码不得使用C++的注释语法“//”，必须使用/*….*/。[必须]
注：本文档的示例中，如有使用“//”，并非代码注释，而是文档的注释(有可能是文档中对代码注释的解释)。
【规则 3-3】说明性文件（如头文件.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:
* 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
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 10 of 46
#endif /* _FILENAME_H */
/*
* $Id$
* $Log$
*
*/
【规则 3-3-1】注：文件末尾的代码用于 CVS 自动生成修改记录。注意在 commit 代码时使用正确的 MR，并
填写充分、准确的注释，这个修改记录是很好用的。所以一般不需要在文件头手工记录修改历史；通常建议只有
对模块进行大规模的、结构性的改动才需要手工记录修改历史。[必须]
【规则 3-3-2】为了防止头文件被重复引用，应当用#ifndef/#define/#endif 结构产生预处理块。[必须]
【规则 3-3-3】用 #include <> 格式来引用标准库的头文件（编译器将从标准库目录开始搜
索）。[必须]
【规则 3-3-4】用 #include “” 格式来引用非标准库的头文件（编译器将从用户的工作目录开始
搜索）。[必须]
【规则 3-3-5】头文件中只存放“声明”而不存放“定义”。(在 C++ 语法中，类的成员函数可以在声明的同
时被定义，并且自动成为内联函数。这虽然会带来书写上的方便，但却造成了风格不一致，弊大于利。建议
将成员函数的定义与声明分开，不论该函数体有多么小。)[建议]
【规则 3-4】源文件头部应进行注释，列出：版权说明、版本号、作者、模块目的/功能、主要函数及其
功能、修改日志等。[必须]
源文件模板示例：
/******************************************************************
* (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:
* Author: Xxxxx
* Description: Template for C source files.
*
* //可选择的增加部分内容
* Function List: //主要函数列表，每个函数一行，包含其返回值类型及参数类型。功能说明应当放在
函数头注释中
* 1. ....
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 11 of 46
* History: // 修改历史记录列表，每条修改记录应包括修改日期、修改
* // 者及修改内容简述。(参见底注)
* 1. Date:
* Author:
* Modification:
* 2. ...
*
***************************************************************/
/*说明：Description一项描述本文件的内容、功能、内部各部分之间的关系及本文件与其它文件关系
等。History是修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述。*/
#include ""
/********************************************************************
*
* 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$
*
*/
【规则 3-4-1】注：文件末尾的代码用于 CVS 自动生成修改记录。注意在 commit 代码时使用正确的 MR，
并填写充分、准确的注释，这个修改记录是很好用的。所以一般不需要在文件头手工记录修改历史；通常建
议只有对模块进行大规模的、结构性的改动才需要手工记录修改历史。[必须]
【规则 3-5】函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用关系
（函数、表）等。[必须]
函数注释模板示例：
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 12 of 46
/****************************************************************************
*
* 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);
【规则 3-5-1】外部函数必须有函数头注释。[必须]
【规则 3-5-2】内部函数强烈建议使用函数头注释。[建议]
【规则 3-6】边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用
的注释要删除。注释的格式尽量统一。 [必须]
示例：
单行注释
/* 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. */
【规则 3-7】注释的内容要清楚、明了，含义准确，防止注释二义性。[建议]
说明：错误的注释不但无益反而有害。
【规则 3-8】避免在注释中使用缩写，特别是非常用缩写。[建议]
说明：在使用缩写时或之前，应对缩写进行必要的说明。
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 13 of 46
【规则 3-9】注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相
邻位置，不可放在下面；如放于上方则需与其上面的代码用空行隔开。[必须]
示例：如下例子不符合规范。
例 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;
【规则 3-10】对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以
注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。[必须]
示例：
示例 1：
/* active statistic task number */
#define SYS_MAX_ACT_TASK_NUMBER 1000
示例 2：
#define SYS_MAX_ACT_TASK_NUMBER 1000 /* active statistic task number */
【规则 3-11】数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以
注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的
右方。[必须]
示例：可按如下形式说明枚举/数据/联合结构。
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 14 of 46
/* 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 network can not
transmission this message */
SCP_UNITDATA_REQ, /* sccp user's unit data transmission request*/
} SCP_USER_PRIMITIVE_T;
【规则 3-12】全局变量要有较详细的注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取
时注意事项等的说明。[必须]
示例：
/* 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;
【规则 3-13】代码中的特殊处理，或者软件work around，必须加注释，注明为何要这样做。[必须]
说明：只有加了注释，以后的维护者才有可能明白前因后果。
【规则 3-14】注释与所描述内容进行同样的缩排。[必须]
说明：可使程序排版整齐，并方便注释的阅读与理解。
示例：如下例子，不正确的布局，排版不整齐，阅读稍感不方便。
不正确的布局：
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
}
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 15 of 46
【规则 3-15】将注释与其上面的代码用空行隔开。[必须]
示例：
如下例子，显得代码过于紧凑：
/* code one comments */
program code one
/* code two comments */
program code two
应如下书写：
/* code one comments */
program code one
/* code two comments */
program code two
【规则 3-16】对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。[建议]
说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程
序。
【规则 3-17】对于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;
...
【规则 3-18】避免在一行代码或表达式的中间插入注释。（S）
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 16 of 46
说明：除非必要（如 PC-LINT 的行禁止检查标记），不应在代码或表达中间插入注释，否则容易使代码可理
解性变差。
【规则 3-19】通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码成为自注释
的。[建议]
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
【规则 3-20】代码的功能、意图层次上进行注释，提供有用、额外的信息。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止
没必要的重复注释信息。
示例：
如下注释意义不大。
/* if receive_flag is TRUE */
if (receive_flag)
而如下的注释则给出了额外有用的信息。
/* if mtp receive a message from links */
if (receive_flag)
【规则 3-21】在程序块的结束行右方加注释标记，以表明某程序块的结束。[可选]
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。Source Insight 可以自动
显示这类信息。
示例：参见如下例子。
if (flag)
{
// program code
while (index < MAX_INDEX)
{
// program code
} /* end of while (index < MAX_INDEX) */ // 指明该条 while 语句结束
} /* end of if (flag)*/ // 指明是哪条 if 语句结束
【规则 3-22】注释应考虑程序易读及外观排版的因素，嵌入式软件的注释必须全部使用英文。[必须]
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 17 of 46
4 标识符命名
【规则 4-1】标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩
写，避免使人产生误解。[建议]
说明：较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大
家公认的缩写。
示例：如下单词的缩写能够被大家基本认可。
temp 可缩写为 tmp ;
flag 可缩写为 flg ;
statistic 可缩写为 stat ;
increment 可缩写为 inc ;
message 可缩写为 msg ;
reserve 可缩写为 resv;
【规则 4-2】命名中若使用特殊约定或缩写，则要有注释说明。[必须]
说明：应该在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进行必要的注释说
明。
【规则 4-3】自己特有的命名风格，要自始至终保持一致，不可来回变化。[建议]
说明：个人的命名风格，在符合所在项目组或产品组的命名规则的前提下，才可使用。（即命名规则中没有
规定到的地方才可有个人命名风格）。
【规则 4-4】常量的定义全部采用大写单词，单词中间以下划线分开，并且各模块中的常量第一个单词必须为
模块头，定义的常数必须加括号。[必须]
示例：
#define RPR_STATUS_CALLBACK （1）
#define RPR_RET_ERR_CODE_NULL （2）
【规则 4-5】结构的命名必须全部为大写字母，第1个单词为模块名，最后一个单词为 "_T"，单词之间以下
划线分开。[必须]
说明：
示例：
typedef struct RVP_MSG_HDR_t
{
UINT32 version:4;
UINT32 resvd:16;
UINT32 msgLen; /* the over all length of the
message, excluding the header*/
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 18 of 46
}RVP_MSG_HDR_T;
typedef struct RVP_RESV_MSG_t
{
RVP_MSG_HDR_T msgHdr;
UINT8 ucSvcNum;
UINT8 ucSvcCode;
UINT16 usSvcLen;
UINT32 unSvcData1;
UINT32 unSvcData2;
UINT32 unSvcData3;
} RVP_RESV_MSG_T;
【规则 4-6】枚举类型的命名必须全部为大写字母，第1个单词为模块名，最后一个单词为 "_T"，单词之间
以下划线分开。[必须]
示例：
typedef enum /* The Instance State Definition */
{
PLB_INST_ERROR=-2,
PLB_INST_DEINIT=-1,
PLB_INST_DEACTIVE=0,
PLB_INST_INIT,
PLB_INST_STANDBY,
PLB_INST_ACTIVE
} PLB_INST_STATE_T;
【规则 4-7】对于变量命名，禁止取单个字符（如i、j、k...），建议除了要有具体含义外，还能表明其
变量类型、数据类型等，但i、j、k作局部循环变量是允许的。[必须]
【规则 4-8】变量名中的大小写与分隔：使用单词首字母大写作为变量中各单词的间隔，变量的打头字
母、打头单词必须小写，禁止使用下划线(“_”)做变量中的分割符。[必须]
例如：
UINT32 dccResetAddr;
STATUS rprInstStatus;
【规则 4-9】全局变量的头部必须有“g+subsystem”的标记，用于区分全局变量的模块范围，同时防止重
名。相同模块内的全局变量必须尽量放在同一个文件中。[必须]
例如：
UINT8 gFmaVariableName;
char gsRprModuleName[RPR_MAX_STRING_LEN];
【规则 4-10-1】模块的全局变量必须组织在同一个结构体中进行管理。[必须]
例如 STP 模块中的全局变量定义如下：
typedef struct
{
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 19 of 46
MIBpbRstpBridgeTable_t stp_gBridgeCfg;
MIBpbRstpPortTable_t stp_gPortCfg[HII_MAX_PORT_NUM];
stp_BridgeData_s stp_gBridgeInfo;
stp_PortData_s stp_gPortInfo[HII_MAX_PORT_NUM];
stp_StateMachine_s stp_gPortSM[HII_MAX_PORT_NUM];
stp_BPDU_s stp_gRcvdBPDU[HII_MAX_PORT_NUM];
int stp_gTimerOneSecond;
}STP_S_STPInfo_T;
在 中采用该结构定义的变量如下：
STP_S_STPInfo_T *stp_gGvar[HII_MAX_INSTANCE_NUM];
【规则 4-11】 变量的前缀表示方法[必须]
类型 描述 前缀 举例
* 指针 P UINT8 *pucIndex;
[] 定长数组 a (optional) UINT8 aMyVar[MAX_LEN];
BOOL 布尔值 B BOOL bMonitored;
char[] 字符串 S char sTtiTx[64];
UINT8 8-bit 无符号整数 uc (optional) UINT8 ucIndex;
or UINT8 index;
UINT16 16-bit 无符号整数 us (optional) UINT16 usPort;
or UINT16 port;
UINT32 32-bit 无符号整数 ul (optional) UINT32 ulErrorCode;
char 可显示字符 c (optional) char cHexHigher4Bits,
cHexLower4Bits;
int 依赖于操作系统的不定长整数
(不建议使用)
n (optnional) int nIndex;
or int j;
UINT 依赖于操作系统的不定长无符
号整数(不建议使用)
u (optional)
Enum 枚举 e (optional)
(other) 其他复杂类型(如结构) 按惯例或自行定义
(注意全局一致)
MSG_Q_ID msgQPmon;
Table 1 变量的前缀
说明：变量的前缀可以由各中前缀组合表示.（变量的命名来自参考文献[1]）
例如：
BOOL gbPslEnabled
UINT32 *gpulHandle;
【规则 4-12】通用类型定义的使用：尽可能使用CTD(Common Type Definitions)中定义的数值类型，尽
量少定义自己的数据类型(在不影响程序可读性的前提下)。[必须]
CTD 包括以下定义：
通用的常量和类型定义，如 UINT8，UINT16，UINT32
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 20 of 46
与 SDH 有关的通用常量和类型定义
通用错误返回码 PB_ERROR_CODE_T
【规则 4-13】除非必要，不要用数字或较奇怪的字符来定义标识符。
示例：如下命名，使人产生疑惑。
#define _RPR_0_TEST_
#define _RPR_1_TEST_
void set_sls00( UINT8 sls );
应改为有意义的单词命名:
#define _RPR_EXAMPLE_UNIT_TEST_
#define _RPR_EXAMPLE_ASSERT_TEST_
void RPR_setUdtMsgSls(UINT8 ucSls );
【规则 4-14】用正确的反义词组命名具有互斥意义的一组变量或相反动作的一组函数等。不得把意义相
反的单词合并在一个变量名或函数名中，以免意义不清。[建议]
说明：下面是一些在软件中常用的反义词组。
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 minSum;
int maxSum;
int addUser( UINT8 *userName );
int deleteUser(UINT8 *userName );
错误：
int addOrDelUser(UINT8 *userName);
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 21 of 46
【规则 4-15】模块必须全部采用 3 个字符，模块的目录 3 个字符必须全部大写(其中第一个字符不得为数
字)，模块下至少有两个子目录，分别为小写的”inc”和”src”。[必须]
项目目录树模板：
SOURCE_ROOT --------include
……
|
+---infra
| |
| +----ZZZ
| ……
+-appl
|
|
+----XXX------inc (exported functions and definitions)
| |
| ---src (source code and private header files)
| |
| ---doc (documents, test plans)
|----YYY------inc
| |
| ---src
| |
| ---doc
-- .....
.
.
其中 ZZZ、XXX、YYY 为模块名
【规则 4-16】模块的外部接口定义应当放在”XXX/inc”目录下；建议把所有接口放在一个文件中，此时一般
可命名为””。[必须]
【规则 4-17】模块的源文件和内部接口定义应当放在”XXX/src”目录下。不得把内部接口与外部接口放在同
一个头文件中。[必须]
注意：并不是所有的头文件都放在 XXX/inc 目录下。只有外部接口才是。如果文件过多，可以考虑在模块中增加
一个子目录(如“XXX/def”)用于存放所有定义内部接口的头文件。
【规则 4-18】模块的属主(owner):每个模块都有一个唯一的属主。[必须]
模块属主的完整列表在””中(见下一条)。
【规则 4-18-1】模块的属主对此模块负责，只有他可以对此模块进行修改。其他工程师不得修改此模块，除
非事先得到属主的批准，并且事后由属主审查。
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 22 of 46
【规则 4-19】模块的正式完整列表维护在 CVS 的根目录下，文本文件””中。
它记录了模块名、模块属主、模块描述。
这个文件一般由项目负责人来维护。
【规则 4-20】文件名的类型与相关的文件扩展名必须遵守如下原则。
文件类型 C H C++ Java Assembler HTML
扩展名 *.c *.h *.cpp *.java *.s *.html
Table 4-1 文件扩展名与文件类型
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 23 of 46
5 可读性
【规则 5-1】注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。[必须]
说明：防止阅读程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。
示例：下列语句中的表达式
word = (high << 8) | low (1)
if ((a | b) && (a & c)) (2)
if ((a | b) < (c & d)) (3)
如果书写为
high << 8 | low
a | b && a & c
a | b < c & d
由于
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)造成了判断条件出错。
【规则 5-2】避免使用不易理解的数字，用有意义的标识来替代。涉及物理状态或者含有物理意义的常
量，不应直接使用数字，必须用有意义的枚举或宏来代替。[必须]
示例：
如下的程序可读性差。
if (ethTrunk[index].trunkState
== 0)
{
ethTrunk[index].trunkState
= 1;
... // program code
}
应改为如下形式。
#define ETH_TRUNK_IDLE 0
#define ETH_TRUNK_BUSY 1
if (ethTrunk[index].trunkState
== ETH_TRUNK_IDLE)
{
ethTrunk[index].trunkState
= ETH_TRUNK_BUSY;
... // program code
}
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 24 of 46
6 变量、结构
【规则 6-1】去掉没必要的公共变量，并禁止用全局变量作为模块间的接口。[必须]
说明：公共变量是增大模块间耦合的原因之一，故应减少没必要的公共变量以降低模块间的耦合度。
绝对不允许全局变量作为模块间的接口。如果绝对必要，可以用函数调用包装起来，并且要考虑用信号量实
现独占访问。
【规则 6-2】仔细定义并明确公共变量的含义、作用、取值范围及公共变量间的关系。
说明：在对变量声明的同时，应对其含义、作用及取值范围进行注释说明，同时若有必要还应说明与其它变
量的关系。
【规则 6-3】当向公共变量传递数据时，要十分小心，防止赋与不合理的值或越界等现象发生。
说明：对公共变量赋值时，若有必要应进行合法性检查，以提高代码的可靠性、稳定性。
【规则 6-4】防止局部变量与公共变量同名。[必须]
说明：若使用了较好的命名规则(【规则 4-9】)，那么此问题可自动消除。
【规则 6-5】严禁使用未经初始化的变量作为右值。在free之后，必须显式把把指针赋值为NULL。[必
须]
说明：特别是在 C/C++中引用未经赋值的指针，经常会引起系统崩溃。
【规则 6-5-1】指针变量在定义的时候，必须赋初值 NULL。[必须]
【规则 6-5-2】指针数组，如果可能(定长数组)，也要在定义时赋初值 NULL；如果不可能(变长数组，或含有
指针的指针)，必须在 malloc 时给指针的指针赋初值 NULL。[必须]
示例：
RPR_GVAR_T *gpRprGVar=NULL;
PLB_GVAR_T *gpPlbGVar[PLB_MAX_INSTANCE_NUM]={NULL, NULL, NULL};
【规则 6-6】变量的命名规则：参见【规则 4-7】【规则 4-8】【规则 4-9】【规则 4-11】[必须]
【规则 6-7】注意数组是从1开始还是从0开始，并注意在这一点上全局风格一致。[必须]
【规则 6-7-1】各模块内部数组实现，数组下标必须从 0 开始，模块间具有下标含义的参数传递必须统
一从 1 开始。[必须]
【规则 6-8】结构中元素的个数应适中。若结构中元素个数过多可考虑依据某种原则把元素组成不同的
子结构，以减少原结构中元素的个数。
说明：增加结构的可理解性、可操作性和可维护性。
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 25 of 46
【规则 6-9】结构的设计要尽量考虑向前兼容和以后的版本升级，并为某些未来可能的应用保留余地
（如预留一些空间等）。
说明：软件向前兼容的特性，是软件产品是否成功的重要标志之一。如果要想使产品具有较好的前向兼容，
那么在产品设计之初就应为以后版本升级保留一定余地，并且在产品升级时必须考虑前一版本的各种特性。
【规则 6-10】合理地设计数据并使用自定义数据类型，避免数据间进行不必要的类型转换。
示例：如下赋值，多数编译器不产生告警，但值的含义还是稍有变化。
char chr;
unsigned short exam;
chr = -1;
exam = chr; // 编译器不产生告警，此时 exam 为 0xFFFF。
【规则 6-11】对自定义数据类型进行恰当命名，使它成为自描述性的，以提高代码可读性。注意其命名
方式在同一产品中的统一，尽可能使用CTD中的定义(参看【规则 4-12】)。[必须]
说明：使用自定义类型，可以弥补编程语言提供类型少、信息量不足的缺点，并能使程序清晰、简洁。
示例：可参考如下方式声明自定义数据类型。
下面的声明可使数据类型的使用简洁、明了(已在 CTD 中定义)。
typedef unsigned char UINT8;
typedef unsigned short UINT16;
typedef unsigned int UINT32;
下面的声明可使数据类型具有更丰富的含义。
typedef float DISTANCE;
typedef float SCORE;
【规则 6-12】当声明用于分布式环境或不同CPU间通信环境的数据结构时，必须考虑机器的字节顺序、
使用的位域及字节对齐等问题。[必须]
说明：比如 Intel CPU 与 68360 CPU，在处理位域及整数时，其在内存存放的“顺序”正好相反。
示例：假如有如下短整数及结构。
unsigned short int exam;
typedef struct EXAM_BIT_STRU
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 26 of 46
{ /* Intel 68360 */
unsigned int A1: 1; /* bit 0 7 */
unsigned int A2: 1; /* bit 1 6 */
unsigned int A3: 1; /* bit 2 5 */
} EXAM_BIT;
如下是 Intel CPU 生成短整数及位域的方式。
内存： 0 1 2 ... （从低到高，以字节为单位）
exam exam 低字节 exam 高字节
内存： 0 bit 1 bit 2 bit ... （字节的各“位”）
EXAM_BIT A1 A2 A3
如下是 68360 CPU 生成短整数及位域的方式。
内存： 0 1 2 ... （从低到高，以字节为单位）
exam exam 高字节 exam 低字节
内存： 7 bit 6 bit 5 bit ... （字节的各“位”）
EXAM_BIT A1 A2 A3
说明：在对齐方式下，CPU 的运行效率要快得多。
示例：如下图，当一个 long 型数（如图中 long1）在内存中的位置正好与内存的字边界对齐时，CPU 存取这
个数只需访问一次内存，而当一个 long 型数（如图中的 long2）在内存中的位置跨越了字边界时，CPU 存取
这个数就需要多次访问内存，如 i960cx 访问这样的数需读内存三次（一个 BYTE、一个 SHORT、一个
BYTE，由 CPU 的微代码执行，对软件透明），所有对齐方式下 CPU 的运行效率明显快多了。
1 8 16 24 32
------- ------- ------- -------
| long1 | long1 | long1 | long1 |
------- ------- ------- -------
| | | | long2 |
------- ------- ------- --------
| long2 | long2 | long2 | |
------- ------- ------- --------
| ....
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 27 of 46
PPC CPU 与INTEL的80x86 CPU的数值存储方式比较：
typedef enum RPR_ENUM_TYPE_t{
UINT8 a[4];
UINT16 b[2];
UINT32 c;
}RPR_ENUM_TYPE_T;
RPR_ENUM_TYPE_T enumType;
[0]=0x1;
[1]=0x2;
[2]=0x3;
[3]=0x4;
PPC CPU中的值分配方式：（BIG ENDIAN 模式）
地址的低位 地址高位
UINT8[0~3] 0x1 0x2 0x3 0x4
UINT16[0~1] 0x12 0x34
UINT32 0x1234
说明：存储方式是低地址放高位数据。
INTEL的80X86值分配方式：(LITTLE ENDIAN 模式)
地址的低位 地址高位
UINT8 0x1 0x2 0x3 0x4
UINT16 0x21 0x43
UINT32 0x4321
说明：存储方式是低地址放低位数据。
【规则 6-13】结构中的变量定义[必须]
说明：结构中的定义要保证结构中变量的长度能够恰好填充内存空间，避免出现内存“空洞”。PPC 目前的字长
度是 32 位，对齐原则是 UINT16(typedef unsigned short UINT16)以 2 字节对齐，UINT32(typedef unsigned int
UINT32)以 4 字节对齐。
示例：
正确的定义:
typedef struct {
UINT8 ucIndex;
UINT8 ucCharValue;
UINT16 usShortValue;
UINT32 ulLongValue;
}SAMPLE_MESSAGE_T;
不正确定义 1：
typedef struct {
UINT8 ucIndex;
/* This var is not 16-bit aligned. */
UINT16 usShortValue;
UINT8 ucCharValue;
UINT32 ulLongValue;
}SAMPLE_MESSAGE_T;
不正确定义 2：:
typedef struct {
UINT8 ucIndex;
UINT8 ucCharValue;
/* This var is not 32-bit aligned. */
UINT32 ulLongValue;
UINT16 usShortValue;
/* This var is neither 16-bit aligned
nor 32-bit aligned. */
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 28 of 46
UINT8 ucCharValue2;
UINT32 ulUglyLong;
}SAMPLE_MESSAGE_T;
说明：各定义在 PPC 内存中的分配方式，其中红色部分为保证对齐时浪费的空间：
正确定义：
Byte 0 byte4 byte8
UINT8 UINT8 UINT16 UINT32
不正确定义 1：
Byte 0 byte4 byte8 byte12
UINT8 UINT16 UINT8 UINT32
不正确定义 2：
Byte 0 byte4 byte8 byte12 byte16
UINT8 UINT8 UINT32 UINT16 UINT8 UINT32
【规则 6-14】常量的定义：参见【规则 4-4】
【规则 6-15】结构体的命名:参见【规则 4-5】
【规则 6-16】枚举类型的命名：参见【规则 4-6】
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 29 of 46
7 宏
【规则 7-1】用宏定义表达式时，要使用完备的括号。[必须]
示例：
如下定义的宏都存在一定的风险。
#define RECTANGLE_AREA( a, b ) a * b
#define RECTANGLE_AREA( a, b ) (a * b)
#define RECTANGLE_AREA( a, b ) (a) * (b)
正确的定义应为：
#define RECTANGLE_AREA( a, b ) ((a) * (b))
【规则 7-2】将宏所定义的多条表达式放在大括号中。[必须]
示例：
下面的语句只有宏的第一条表达式被执行。为了说明问题，for 语句的书写稍不符规范。
#define INTI_RECT_VALUE( a, b )\
a = 0;\
b = 0;
for (index = 0; index < RECT_TOTAL_NUM; index++)
INTI_RECT_VALUE( , );
正确的用法应为：
#define INTI_RECT_VALUE( a, b ) \
{ \
a = 0; \
b = 0; \
}
for (index = 0; index < RECT_TOTAL_NUM; index++)
{
INTI_RECT_VALUE( rect[index].a, rect[index].b );
}
或者采用如下的写法：
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 30 of 46
#define INTI_RECT_VALUE( a, b ) \
do { \
a = 0; \
b = 0; \
}while(0)
说明：在花括号外加上 do..while(0)语句，聪明的你一定知道它的用处：）
【规则 7-3】使用宏时，不允许参数发生变化。[必须]
示例：
如下用法可能导致错误。
#define SQUARE( a ) ((a) * (a))
int a = 5;
int b;
b = SQUARE( a++ ); // 结果：a = 7，即执行了两次增 1。
正确的用法是：
b = SQUARE( a );
a++; // 结果：a = 6，即只执行了一次增 1。
【规则 7-4】宏内部定义暂态变量时，暂态变量名不得与宏输入参数重名。[必须]
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 31 of 46
8 函数、过程
注意：函数的关键输入参数（如指针、下标等）必须进行参数检查；函数的返回值必须进行适当处理。
【规则 8-1】对所调用函数的返回值和错误返回码要仔细、全面地处理。[必须]
【规则 8-2】编写可重入函数时，应注意局部变量的使用（如编写C/C++语言的可重入函数时，应使用
auto即缺省态局部变量或寄存器变量）。[必须]
说明：编写 C/C++语言的可重入函数时，不应使用 static 局部变量，否则必须经过特殊处理，才能使函数具
有可重入性。
【规则 8-3】编写可重入函数时，若使用全局变量，则应通过关中断、信号量等手段对其加以保护。[必
须]
说明：若对所使用的全局变量不加以保护，则此函数就不具有可重入性，即当多个进程调用此函数时，很有
可能使有关全局变量变为不可知状态。
示例：
假设 Exam 是 int 型全局变量，函数 Squre_Exam 返回 Exam 平方值。那么如下函数不具有可重入性。
unsigned int example( int para )
{
unsigned int temp;
Exam = para; // （**）
temp = Square_Exam( );
return temp;
}
此函数若被多个进程调用的话，其结果可能是未知的，因为当（**）语句刚执行完后，另外一个使用本函数
的进程可能正好被激活，那么当新激活的进程执行到此函数时，将使 Exam 赋与另一个不同的 para 值，所以
当控制重新回到“temp = Square_Exam( )”后，计算出的 temp 很可能不是预想中的结果。此函数应如下改进。
unsigned int example( int para )
{
unsigned int temp;
[申请信号量操作] // 若申请不到“信号量”，说明另外的进程正处于
Exam = para; // 给 Exam 赋值并计算其平方过程中（即正在使用此
temp = Square_Exam( ); // 信号），本进程必须等待其释放信号后，才可继
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 32 of 46
[释放信号量操作] // 续执行。若申请到信号，则可继续执行，但其
// 它进程必须等待本进程释放信号量后，才能再使
// 用本信号。
return temp;
}
【规则 8-4】在同一项目组应明确规定对接口函数参数的合法性检查应由函数的调用者负责还是由接口
函数本身负责，缺省是由被调用者负责。[必须]
说明：对于模块间接口函数的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调
用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；要么就是调
用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。
【规则 8-5】函数的输入参数如果是指针，必须使用 const 修饰，以防止其内容被改变。[必须]
说明：这样做，既可以从编译这个层次就防止了隐患，又增加了代码的可读性。
【规则 8-6】函数的输出参数如果是指针，应防止将其作为工作变量。[建议]
说明：将函数的参数作为工作变量，有可能错误地改变参数内容，所以很危险。对必须改变的参数，最好先
用局部变量代之，最后再将该局部变量的内容赋给该参数。
示例：下函数的实现不太好。
void rpr_sumData( unsigned int num, int *data, int *sum )
{
unsigned int count;
*sum = 0;
for (count = 0; count < num; count++)
{
*sum += data[count]; // sum 成了工作变量，不太好。
}
}
若改为如下，则更好些。
void rpr_sumData( unsigned int num, const int *data, int *sum )
{
unsigned int count ;
int sumTemp;
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 33 of 46
sumTemp = 0;
for (count = 0; count < num; count++)
{
sumTemp += data[count];
}
*sum = sumTemp;
}
【规则 8-7】函数的规模尽量限制在200行以内。
说明：不包括注释和空格行。
【规则 8-8】小心使用 BOOL 参数。在意义明显时，尽量使用 BOOL 类型，同时在变量命名中使 TRUE
与 FALSE 的含义不证自明；在意义不明显时，不要使用 BOOL 类型。
【规则 8-9】当一个过程（函数）中对较长变量（一般是结构的成员）有较多引用时，可以用一个意义
相当的宏代替。[建议]
说明：这样可以增加编程效率和程序的可读性。
示例：
在某过程中较多引用 rprTheReceiveBuffer[rprFirstSocket].ucDataPtr；
则可以通过以下宏定义来代替：
# define pSOCKDATA rprTheReceiveBuffer[rprFirstScoket].ucDataPtr
【规则 8-10】为简单功能编写函数。
说明：虽然为仅用一两行就可完成的功能去编函数好象没有必要，但用函数可使功能明确化，增加程序可读
性，亦可方便维护、测试。
示例：如下语句的功能不很明显。
value = ( a > b ) ? a : b ;
改为如下就很清晰了。
int max (int a, int b)
{
return ((a > b) ? a : b);
}
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 34 of 46
value = max (a, b);
或改为如下。
#define MAX (a, b) (((a) > (b)) ? (a) : (b))
value = MAX (a, b);
【规则 8-11】不要设计多用途面面俱到的函数。[建议]
说明：多功能集于一身的函数，很可能使函数的理解、测试、维护等变得困难。
【规则 8-12】避免设计多参数函数。一方面，不使用的参数从接口中去掉；另一方面，把关系非常紧密
的一系列参数定义成一个结构，并把其指针作为函数参数。[建议]
说明：目的减少函数间接口的复杂度。(说明：目前通过 PC-LINT 检查，CVS 代码中这种现象比较严重)
【规则 8-13】非调度函数应减少或防止控制参数，尽量只使用数据参数。[建议]
说明：本建议目的是防止函数间的控制耦合。调度函数是指根据输入的消息类型或控制命令，来启动相应的
功能实体（即函数或过程），而本身并不完成具体功能。控制参数是指改变函数功能行为的参数，即函数要根据
此参数来决定具体怎样工作。非调度函数的控制参数增加了函数间的控制耦合，很可能使函数间的耦合度增大，
并使函数的功能不唯一。
示例：
如下函数构造不太合理。
int add_sub( int a, int b, unsigned char add_sub_flg )
{
if (add_sub_flg == INTEGER_ADD)
{
return (a + b);
}
else
{
return (a b);
}
}
不如分为如下两个函数清晰。
int add( int a, int b )
{
return (a + b);
}
int sub( int a, int b )
{
return (a b);
}
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 35 of 46
【规则 8-14】检查函数所有非参数输入的有效性，如数据文件、公共变量等。[建议]
说明：函数的输入主要有两种：一种是参数输入；另一种是全局变量、数据文件的输入，即非参数输入。
函数在使用输入之前，应进行必要的检查。
【规则 8-15】函数名应准确描述函数的功能。
【规则 8-15-1】使用动宾词组为执行某操作的函数命名。如果是 OOP 方法，可以只有动词（名词是对象
本身）。
示例：参照如下方式命名函数。
void rpr_printRecord( unsigned int unRecInd ) ;
int rpr_inputRecord( void ) ;
unsigned char rpr_getCurrentColor( void ) ;
【规则 8-15-2】避免使用无意义或含义不清的动词为函数命名。
说明：避免用含义不清的动词如 process、handle 等为函数命名，因为这些动词并没有说明要具体做什么。
【规则 8-16】函数的返回值要清楚、明了，让使用者不容易忽视错误情况。尽量使用 CTD 中的通用错误类
型定义(参见【规则 4-12】)。 [建议]
说明：函数的每种出错返回值的意义要清晰、明了、准确，防止使用者误用、理解错误或忽视错误返回
码。
【规则 8-17】除非必要，最好不要把与函数返回值类型不同的变量，以编译系统默认的转换方式或强制的转
换方式作为返回值返回。
【规则 8-18】在调用函数填写参数时，应尽量减少没有必要的默认数据类型转换或强制数据类型转换。
说明：因为数据类型转换或多或少存在危险。[建议]
【规则 8-19】避免函数中不必要语句，防止程序中的垃圾代码。[建议]
说明：程序中的垃圾代码不仅占用额外的空间，而且还常常影响程序的功能与性能，很可能给程序的测
试、维护等造成不必要的麻烦。
【规则 8-20】防止把没有关联的语句放到一个函数中。
说明：防止函数或过程内出现随机内聚。随机内聚是指将没有关联或关联很弱的语句放到同一个函数或过程
中。随机内聚给函数或过程的维护、测试及以后的升级等造成了不便，同时也使函数或过程的功能不明确。使用
随机内聚函数，常常容易出现在一种应用场合需要改进此函数，而另一种应用场合又不允许这种改进，从而陷入
困境。
在编程时，经常遇到在不同函数中使用相同的代码，许多开发人员都愿把这些代码提出来，并构成一个新函
数。若这些代码关联较大并且是完成一个功能的，那么这种构造是合理的，否则这种构造将产生随机内聚的函
数。
示例：
如下函数就是一种随机内聚。
void Init_Var( void )
{
= 0;
= 0; /* 初始化矩形的长与宽 */
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 36 of 46
= 10;
= 10; /* 初始化“点”的坐标 */
}
矩形的长、宽与点的坐标基本没有任何关系，故以上函数是随机内聚。
应如下分为两个函数：
void Init_Rect( void )
{
= 0;
= 0; /* 初始化矩形的长与宽 */
}
void Init_Point( void )
{
= 10;
= 10; /* 初始化“点”的坐标 */
}
【规则 8-21】如果多段代码重复做同一件事情，那么在函数的划分上可能存在问题。
说明：若此段代码各语句之间有实质性关联并且是完成同一件功能的，那么可考虑把此段代码构造成一个新
的函数。
【规则 8-22】功能不明确较小的函数，特别是仅有一个上级函数调用它时，应考虑把它合并到上级函数中，
而不必单独存在。
说明：模块中函数划分的过多，一般会使函数间的接口变得复杂。所以过小的函数，特别是扇入很低的或功
能不明确的函数，不值得单独存在。
【规则 8-23】设计高扇入、合理扇出（小于 7）的函数。[建议]
说明：扇出是指一个函数直接调用（控制）其它函数的数目，而扇入是指有多少上级函数调用它。
扇出过大，表明函数过分复杂，需要控制和协调过多的下级函数；而扇出过小，如总是 1，表明函数的调用
层次可能过多，这样不利程序阅读和函数结构的分析，并且程序运行时会对系统资源如堆栈空间等造成压力。函
数较合理的扇出（调度函数除外）通常是 3-5。扇出太大，一般是由于缺乏中间层次，可适当增加中间层次的函
数。扇出太小，可把下级函数进一步分解多个函数，或合并到上级函数中。当然分解或合并函数时，不能改变要
实现的功能，也不能违背函数间的独立性。
扇入越大，表明使用此函数的上级函数越多，这样的函数使用效率高，但不能违背函数间的独立性而单纯地
追求高扇入。公共模块中的函数及底层函数应该有较高的扇入。
较良好的软件结构通常是顶层函数的扇出较高，中层函数的扇出较少，而底层函数则扇入到公共模块中。
【规则 8-24】减少函数本身或函数间的递归调用。[建议]
说明：递归调用特别是函数间的递归调用（如 A->B->C->A），影响程序的可理解性；递归调用一般都占用
较多的系统资源（如栈空间）；递归调用对程序的测试有一定影响。故除非为某些算法或功能的实现方便，应减
少没必要的递归调用。
【规则 8-25】仔细分析模块的功能及性能需求，并进一步细分，同时若有必要画出有关数据流图，据此来进
行模块的函数划分与组织。[建议]
说明：函数的划分与组织是模块的实现过程中很关键的步骤，如何划分出合理的函数结构，关系到模块的最
终效率和可维护性、可测性等。根据模块的功能图或/及数据流图映射出函数结构是常用方法之一。
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 37 of 46
【规则 8-26】改进模块中函数的结构，降低函数间的耦合度，并提高函数的独立性以及代码可读性、效率和
可维护性。优化函数结构时，要遵守以下原则：[建议]
（1）不能影响模块功能的实现。
（2）仔细考查模块或函数出错处理及模块的性能要求并进行完善。
（3）通过分解或合并函数来改进软件结构。
（4）考查函数的规模，过大的要进行分解。
（5）降低函数间接口的复杂度。
（6）不同层次的函数调用要有较合理的扇入、扇出。
（7）函数功能应可预测。
（8）提高函数内聚。（单一功能的函数内聚最高）
说明：对初步划分后的函数结构应进行改进、优化，使之更为合理。
【规则 8-28】禁止在向外提供接口的头文件中定义 static inline 函数。[必须]
说明：如果向外提供接口的头文件中定义了 static inline 函数，并且该头文件被外部模块所包含，同时包含
该头文件的模块没有调用该 static inline 函数（往往外部模块包含该头文件是为了使用其中的结构定义或者函
数申明），则编译时将会出现告警，该现象在系统中是不允许的。
【规则 8-29】禁止在头文件中函数申明时加入 extern 标记，各模块调用外部函数时禁止采用 extern 的形
式申明该函数，必须采用包含头文件的方式申明该函数。[必须]
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 38 of 46
9 可测性
【规则 9-1】在同一项目组或产品组内，调测打印出的信息串的格式要有统一的形式。信息串中至少要
有所在模块名（或源文件名）、行号。[必须]
说明：统一的调测信息格式便于集成测试。否则串口上跳出一句莫名其妙的打印，不知是谁打的。
【规则 9-2】编程的同时要为单元测试选择恰当的测试点，并仔细构造测试代码、测试用例，同时给出
明确的注释说明。测试代码部分应作为（模块中的）一个子模块，以方便测试代码在模块中的安装与拆
卸（通过调测开关）。[建议]
【规则 9-3】在进行集成测试/系统联调之前，要构造好测试环境、测试项目及测试用例，同时仔细分析
并优化测试用例，以提高测试效率。[建议]
说明：好的测试用例应尽可能模拟出程序所遇到的边界值、各种复杂环境及一些极端情况等。
【规则 9-4】软件模块必须设计和提供完善的TCL DEBUG的命令。[必须]
说明：参考文献[2][3]中提供了 MetroWave 系列产品 TCL DEBUG 中的实现机制，参考嵌入式软件库中各模
块的 TCL 代码的组织。
【规则 9-5】软件模块必须设计和提供完善的DEBUG打印信息控制，打印信息开关必须分级控制。[必
须]
说明：参考文献[2][3]中提供了 MetroWave 系列产品相关实现机制，或者参考代码 RPR 模块中的打印信息控
制。同时建议打印开关必须与实例(instance)独立，即开关控制参数支持多 instance。
示例：（该示例来自参考文献[3]）
头文件
#include “”
/* Anonymous enum that contains DBG levels. It shall comply with gDghSelfInfo. */
enum {
S1W_FAIL = 0,
S1W_BASIC ,
S1W_FUNC ,
S1W_INT ,
S1W_TIMER ,
S1W_ISR,
};
extern DBG_MODULE_T gDbgS1wModNum;
#define S1W_DBG(msg, level) DBG_Print(msg, gDbgS1wModNum, level)
#define S1W_DBG2(msg, level1, level2) DBG_Print2And(msg, gDbgS1wModNum, level1, level2)
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 39 of 46
实现文件 :
DBG_INFO_T gDbgS1wInfo = {
"S1W",
{
{"FAIL" , 0, "When error occurs."},
{"BASIC" , 0, ""},
{"FUNC" , 0, "Function entry/exit"},
{"INT" , 0, "Interrupt handling."},
{"TIMER" , 0, "Timer related - it may be printed repeatedly."},
{"ISR" , 0, "ISR - do not enable in unless in NVRAM."},
}
};
DBG_MODULE_T gDbgS1wModNum;
S1W_Init()
{
gDbgS1wModNum = DBG_RegisterModule(&gDbgS1wInfo);
/* More initializations… */
S1W_DBG((“My message: %d\r\n”, myParam), S1W_INIT);
}
void MY_Timer()
{
S1W_DBG2((“Timer triggered! No %d\r\n”, myParam), S1W_INT, S1W_TIMER);
/* … */
}
【规则 9-6】禁止在模块代码中直接使用”printf”打印控制信息。每个模块必须设计独立的打印信息函数
(参见上一条)，打印开关必须全部默认为关闭，打印信息的长度必须控制在75字节以内。[必须]
示例：
本示例说明了模块代码中采用两层封装实现打印信息函数的一种方式。
void PLB_Print(char *fmt,...)
{
va_list vaObj;
char buf[500];
va_start(vaObj, fmt);
vsprintf(buf, fmt, vaObj);
if(gPlbDbgLogCtrl&PLB_DBG_CTRL_ON)
{
#ifdef PLB_SMC_PRINT_ON
smcPrint("%s :tick=%u \r\n",buf,tickGet());
#els
printf("%s :tick=%u \r\n",buf,tickGet());
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 40 of 46
#endif
}
va_end(vaObj);
return;
}
void PLB_Log(char *filename,UINT32 line,int nErrCode,char *fmt,...)
{
va_list vaObj;
char buf[500];
va_start(vaObj, fmt);
vsprintf(buf, fmt, vaObj);
if(gPlbDbgLogCtrl&PLB_LOG_CTRL_ON)
{
ulogit(line, filename,nErrCode,
"ErrCode=%x:%s:tick=%lu",
nErrCode,
buf,
tickGet());
}
#ifdef PLB_DBG_MODE_ON
PLB_Print("PLB-Log:line=%d file=%s err=%d msg=%s",line, filename, nErrCode,buf);
#endif
va_end(vaObj);
return;
}
在代码中调用以上两函数的方式如下：
if(PLB_DBG_CHK(instance,PLB_DBG_LEVEL_MAIN))
{
PLB_Print("PLB Check Instance or IfIdx Error(tpTask)!instance=%d ifIdx=%d",instance,ifIdx);
}
【规则 9-7】软件模块必须编写防错程序，处理错误状态，然后在处理错误之后可用断言宣布发生错误或
者用 LOG 方式记录错误信息。[必须]
【规则 9-8】准确估计打印的频率，不要弄得串口上不停地打印垃圾(即使是调试开关打开的时候)。
【规则 9-9】注意串口的打印速率是很慢的。某些对时间非常敏感的问题，可能在调试开关关闭时出现，而在
调试开关打开、打印很多时，不再出现。
10 代码版本管理
本章没有按照《规则N-M》的格式编排，因为它是在执行过程中的流程。
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 41 of 46
代码质量定义
对于每个模块的每一行code来说，代码质量定义如下：
一级：临时性的 （可能是出于联调目的提供）
二级：可编译通过
三级: 软件自测已经完成 （可以放到代码分支上去）
四级：已经经过至少一轮的SVT的测试 （有一定的代码质量）
五级：GA 质量
CVS 分支定义
分支： project manager (可委托load builder) 创建，每个release 只有一个，用于出正式的load 给
SVT 。
主干： 是一个特殊的分支，缺省情况下把它定义为当前release的分支。 (如有必要，Project
Manager可以特别向大家强调这一点。)
临时分支： 各人为了调试目的自己创建，
TAG： 是一种标记和记录点。
主干和分支的关系：
以 805 为例，CVS 的分支和主干的关系如下：
主干的意义与时间有关，T1 之前，主干就是 ，T1 之后，主干是 ，T2 之后，主干是
CVS 代码引入规定
必须时刻保持各Release分支(包括主干)代码的质量，绝对不可以把它作为垃圾场 。如有违反，任何发现违反
的工程师要报告给Project Manager，由Project Manager找到肇事者责令其立即更正，并报Function Manager /
Team Leader备案。
Before NEI阶段：至少二级以上质量的代码才可以放入分支， 其余代码在临时分支（或本机）上进行。
A）在上NE测试前：只可以commit除 ,以外的代码（见下章CVS代码Commit顺序）
B）在上NE测试阶段：此时commit ,的代码，以确保代码在NE上是可用的。
NEI进行阶段： 至少二级以上质量的代码才可以放入分支， 其余代码在临时分支（或本机）上进行。
Bug Fix阶段： 三级以上质量的代码才可以放入分支， 其余代码在临时分支（或本机）上进行。 这也
意味着一个涉及多模块的MR ，其代码提交对CVS分支来看是一个原子操作。
除此以外的代码都只能放在自己创建的临时分支，或者本机上。
这样做看起来是增加了代码挪动的工作量，但是可以提高代码的稳定性，避免互相影响带来的工作效率的极
大下降。
CVS 代码 Commit 顺序
如果注意 commit 顺序，可以保证任意时刻 CVS 中的代码都是可以编译通过的。
1、修改代码(无新增文件)时：
a) 先commit头文件；如果涉及多个模块的头文件，须把各模块所有头文件commit；
b) 再commit C文件。
T2
Main trunk
T1
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 42 of 46
2、有新增模块和文件时：
a) 先commit新模块的头文件 ；
b) 修改 (或者类似文件)，将新模块的路径加入；(从这一时刻开始，旧模块可以开始在本地写
coding，增加对新模块接口的调用并进行本地编译)
c) 保证新模块的C文件编译、运行无误，将其与模块自己的makefile一并commit；
d) 修改全局makefile并commit；
e) 修改 (801)或者(809/805/800)，将新模块加载，并commit；
f) 最后commit原有模块，增加对新模块接口的调用。
Commit 文件过程中的其他注意事项
1、commit 代码结束后，对 CVS 根目录使用 search modified 功能(菜单 Macros->Search->Fast Search Modified
“MWxxx”)，确认是否还有本地修改的文件未 commit。通过这个办法严格避免漏 commit 文件导致编译不过。
2、commit 每个文件前，一定要使用工具软件（如：Araxis Merge, Beyond Compare 2）将要 commit 的文件同 cvs
上的该文件做详细比较，既确保差别部分都是自己要做的修改，切不可覆盖 cvs 上其他人的修改；又确保没有多
余的修改(如垃圾 printf)进入 CVS 中。
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 43 of 46
11 附录 A – 推荐编辑器的默认配置修改
UntraEdit 默认配置修改
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 44 of 46
Source-Insight 默认配置修改
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 45 of 46
12 附录 B– PC-LINT 的使用简介
本附录提供了 PC-LINT 使用的简要介绍，详细的 PC-LINT 使用说明见参考文献[10]中。
PC-LINT 的软件包说明
PC-LINT 软件包下载地址：
T:\projects\Software\Infra\Programmer's Guide\
或： T:\projects\Software\Infra\Programmer's Guide\lint\.
或： T:\projects\Software\01_tiger_team\03_pc-lint
文件内容：
和 ： PC-Lint 的执行文件(两个不同版本，且较新)。
: PC-Lint的官方说明文件。
： PC-Lint的出错检查编号。在中亦包含该内容。
和 ： PB的PC-Lint检查规则定义参数选项。该两个文件由infra提供的。
PC-LINT 的使用步骤
（1） 首先把 和 拷贝到本机的编译工具目录(一般为本地的 TOOLS 目录)。
（2） 第二步把“”和“”拷贝到所编译项目的根目录下。
如：“.MW8100\.” 或者“.MW809\.”根目录。
（3） 第三步在自己所编写模块的 src 目录下(如 D:\ztemp\MW809\appl\RPR\RPP\src，注意是 src 目录) ，在
MAKEFILE 文件的最后添加一行“include $(PB_BASE)/”(注意，前面没有”－”的符号)。
（4） 从 DOS 命令行模式进入所修改的 MAKEFILE 的 src 目录(即需要检查的源代码所在目录，注意是“src”目
录)，执行 : make catcher 命令。 生成的 文件为错误信息文件，如果没有错误信息，将会生成
文件。xxx 是本地的模块名字。执行：make pitcher 命令可以删除 PC-LINT 的检查结果。
（5） 在该 src 目录中生成的 文件中，详细列出了 PC-LINT 代码检查结果，模块的 owner 依据该检查结果
CHECK 各自的模块代码。
比如：附录中的 RPP 模块检查的部分结果为如下(为方便说明，前面加入了行号)：
000001 }
000002 #
000003 (281): @@@Error 715: Symbol 'nIndata' (line 221) not referenced
000004 }
000005 #
000006 (351): @@@Error 715: Symbol 'interp' (line 332) not referenced
000007 (351): @@@Error 715: Symbol 'clientData' (line 332) not referenced
000008 }
000009 #
000010 (373): @@@Error 715: Symbol 'interp' (line 353) not referenced
000011 (373): @@@Error 715: Symbol 'clientData' (line 353) not referenced
Project MetroWave General
Section SW Engineering
File Name 嵌入式软件编程规范
Document Number:
SW-00-00-0004
Revision:
Date: 2005-1-3
Process Owner: QA Team
Copyright @2005 Photonic Bridges Inc. (Company Confidential) Page 46 of 46
说明：第 000003 行为第一个检查出的错误，错误编号是 715，该出错位置为 文件中的 281
行，该行的代码为上面 000001－000002 行中。
PC-LINT 的使用规则(By FuJili)
（1）PC-Lint 使用的最佳时间是代码修改后测试前；
（2）对于 PC-Lint 的结果，应该尽可能的修改代码来消除告警，而不是通过告警压制来消除，必须要进
行告警压制的，应该采用逐行压制的方法；
（3）需要统一进行压制的告警应该尽可能少，并由专责人员进行严格的统一的控制；所有告警压制必
须有详细的说明，并经过审查；
（4）修改代码时涉及到存在告警压制的代码的时候，应该把相关的告警压制去掉，重新进行 PC-Lint 的
检查；
（5）PC-Lint 检查的目的主要是减少语法错误和基本逻辑错误，既不能替代编译器检查，也不能替代测
试，其作用主要体现在加快检查低级错误的速度，提高测试初期的效率，对于较为复杂的逻辑错误、时序错
误、设计错误等是无能为力的；
