嵌入式软件编程规范

TRZN

TRZN 嵌入式软件编程规范

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN 领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 文档修改历史： 版本号 日期 0.1

2016-10-28 修改者及常用邮箱 杨科 ykee126@126.com 修改日志 根据查阅的相关资料整理，此版本为第一次提交。 仅限项目组内部传阅 Page 2 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN 1 1.1 1.2 2 3 4 5 6 7 8 9 10 10.1 10.2 10.3 10.4 10.5 11 11.1

领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 文档概述 ...................................................................................................................................................................... 4 关于本文档 .............................................................................................................................................................. 4 参考文献 .................................................................................................................................................................. 4 排版 .............................................................................................................................................................................. 5 注释 ............................................................................................................................................................................ 10 标识符命名 ................................................................................................................................................................ 19 可读性 ........................................................................................................................................................................ 25 变量、结构 ................................................................................................................................................................ 26 宏 ................................................................................................................................................................................ 31 函数、过程 ................................................................................................................................................................ 33 可测性 ........................................................................................................................................................................ 41 代码版本管理 ............................................................................................................................................................ 44 代码质量定义 ........................................................................................................................................................ 44 GIT分支定义 ......................................................................................................................................................... 44 GIT代码引入规定 ................................................................................................................................................. 44 GIT代码COMMIT顺序 .......................................................................................................................................... 45 COMMIT文件过程中的其他注意事项 .................................................................................................................. 45 附录A – 推荐编辑器的默认配置修改 .................................................................................................................... 46 KEIL UVISION5默认配置修改 ............................................................................................................................... 46

仅限项目组内部传阅 Page 3 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN

领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 1 文档概述

1.1 关于本文档

本文档规范了芜湖天人智能有限公司嵌入式软件部软件代码的书写规范和原则。

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

公司机密，严禁外传。

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

其中[标记]的含义如下：

（必须） ： 表示该条规则是必须遵守的。 （建议） ： 表示该条规则是建议遵守的。 （可选）或没有标记 ： 表示该条规则是可选择遵守的。

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

1.2 参考文献

[1]高质量C++编程 [2]Effective C++

[3]More Effective C++ [4]C++ Primer [5]Thinking in C++

仅限项目组内部传阅 Page 4 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN

领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 2 排版

? 【规则 2-1】程序块要采用缩进风格编写，缩进的空格数为4个,对齐使用空格键，不得使用TAB键。

[必须]

嵌入式软件开发的代码编辑器，推荐使用Keil uVision5，编辑器参数设置见附录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字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操

作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。[必须]

示例：

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));

? 【规则 2-4】循环、判断等语句中若有较长的表达式或语句，则要进行适当的分行，长表达式要在低

优先级操作符处划分新行，操作符放在行尾。[必须]

示例：

仅限项目组内部传阅 Page 5 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN

领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 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】结构中元素的个数应适中。若结构中元素个数过多可考虑依据某种原则把元素组成不同的

子结构，以减少原结构中元素的个数。

仅限项目组内部传阅 Page 26 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN 领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 说明：增加结构的可理解性、可操作性和可维护性。

? 【规则 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，在处理位域及整数时，其在内存存放的“顺序”正好相反。 示例：假如有如下短整数及结构。

仅限项目组内部传阅 Page 27 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN 领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 unsigned short int exam; typedef struct EXAM_BIT_STRU

{ /* 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 | | ------- ------- ------- -------- | ....

仅限项目组内部传阅 Page 28 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN 领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部

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; enumType.a[0]=0x1; enumType.a[1]=0x2; enumType.a[2]=0x3; enumType.a[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字节对齐。

示例： 正确的定义: 不正确定义1： 不正确定义2：: typedef struct { typedef struct { typedef struct { UINT8 ucIndex; UINT8 ucIndex; UINT8 ucIndex; UINT8 ucCharValue; /* This var is not 16-bit aligned. */ UINT8 ucCharValue; UINT16 usShortValue; /* This var is not 32-bit aligned. */ UINT16 usShortValue; 仅限项目组内部传阅 Page 29 of 47

项目： Embedded software development 文件号: SW-00-00-0001 版本号: 0.1 日期: 2016-10-28 TRZN 领域： SW Engineering 文件名称： 嵌入式软件编程规范 所属部门: 电控质量管理部 UINT32 ulLongValue; UINT8 ucCharValue; }SAMPLE_MESSAGE_T; UINT32 ulLongValue; }SAMPLE_MESSAGE_T; UINT32 ulLongValue; UINT16 usShortValue; /* This var is neither 16-bit aligned nor 32-bit aligned. */ 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】

仅限项目组内部传阅 Page 30 of 47

本文来源：https://www.bwwdw.com/article/3xr3.html