嵌入式软件开发编程规范及原则

编程规范也就是编写出简洁、可维护、可靠、可测试、高效、可移植的代码，提高产品代码的质量。本文针对嵌入式，主要结合C语言编程的规范给大家讲述。

1.头文件

对于C语言来说，头文件的设计体现了大部分的系统设计，不合理的头文件布局是编译时间过长的原因。

有很多人将工程中所有的头文件包含在一个include.h文件中，然后在每一个.c源代码文件中包含include.h头文件，这样做可以让代码看上去简洁，但实际忽视了编译效率问题，而且代码的可移植性也不好。

原则：

A.头文件中适合放置接口的声明，不适合放置实现；

B.头文件应当职责单一;

C.头文件应向稳定的方向包含。

规则：

A.每一个.c文件应有一个同名.h文件，用于声明需要对外公开的接口;

B.禁止头文件循环依赖;

C..c/.h文件禁止包含用不到的头文件;

D.头文件应当自包含;

E.总是编写内部#include保护符（ #define 保护）;

F.禁止在头文件中定义变量;

G.只能通过包含头文件的方式使用其他.c提供的接口，禁止在.c中通过extern的方式使用外部函数接口、变量;

H.禁止在extern "C"中包含头文件。

建议：

A.一个模块通常包含多个.c文件，建议放在同一个目录下，目录名即为模块名。为方便外部使用者，建议每一个模块提供一个.h，文件名为目录名;

B.如果一个模块包含多个子模块，则建议每一个子模块提供一个对外的.h，文件名为子模块名（降低接口使用者的编写难度）;

C.头文件不要使用非习惯用法的扩展名，如.inc;

D.同一产品统一包含头文件排列方式。

2.函数

函数设计的要点：编写整洁的函数，同时把代码有效组织起来。

函数整洁的要求：代码简单直接、不隐藏设计者的意图、用干净利落的抽象和直截了当的控制语句将函数有机组织起来。

原则：

A.一个函数仅完成一件功能;

B.重复代码应该尽可能提炼成函数.

规则：

A.避免函数过长，新增函数不超过100行（非空非注释行）;

B.避免函数的代码块嵌套过深，新增函数的代码块嵌套不超过4层;

C.可重入函数应避免使用共享变量；若需要使用，则应通过互斥手段（关中断、信号量）对其加以保护;

D.对参数的合法性检查，由调用者负责还是由接口函数负责，应在项目组/模块内应统一规定;

E.对函数的错误返回码要全面处理;

F.设计高扇入，合理扇出（小于7）的函数;

G.废弃代码（没有被调用的函数和变量)要及时清除。

建议：

A.函数不变参数使用const;

B.函数应避免使用全局变量、静态局部变量和I/O操作，不可避免的地方应集中使用;

C.检查函数所有非参数输入的有效性，如数据文件、公共变量等;

D.函数的参数个数不超过5个;

E.除打印类函数外，不要使用可变长参函数;

F.在源文件范围内声明和定义的所有函数，除非外部可见，否则应该增加static关键字。

3.标识符命名与定义

程序命名是一个关键，如果命名不规范，自己写的代码，时间长了恐怕连自己都不知道是什么意思了。

3.1通用命名规则

常见命名风格：

A.用下划线„_‟分割，如text_mutex;

B.大小写字母混用，如ReadRFCText。

规则：

A.标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解；

B.除了常见的通用缩写以外，不使用单词缩写，不得使用汉语拼音;

C.产品/项目组内部应保持统一的命名风格.

建议：

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

B.尽量避免名字中出现数字编号，除非逻辑上的确需要编号;

C.标识符前不应添加模块、项目、产品、部门的名称作为前缀;

D.平台/驱动等适配代码的标识符命名风格保持和平台/驱动一致;

E.重构/修改部分代码时，应保持和原有代码的命名风格一致。

3.2 文件命名规则

因为不同系统对文件名大小写处理会不同，建议文件命名统一采用小写字符。

3.3 变量命名规则

首先，全局变量十分危险，通过前缀使得全局变量更加醒目， 促使开发人员对这些变量的使用更加小心。

其次，从根本上说，应当尽量不使用全局变量，增加g_和s_前缀，会使得全局变量的名字显得很丑陋，从而促使开发人员尽量少使用全局变量。

规则：

A.全局变量增加“g_”前缀，静态变量增加“s_”前缀;

B.禁止使用单字节命名变量，但允许定义i、 j、 k作为局部循环变量;

C.使用名词或者形容词＋名词方式命名变量。

3.4 函数命名规则

A.函数命名应以函数要执行的动作命名，一般采用动词或者动词＋名词的结构;

B.函数指针除了前缀，其他按照函数的命名规则命名。

3.5 宏的命名规则

A.对于数值或者字符串等等常量的定义，建议采用全大写字母，单词之间加下划线„_‟的方式命名（枚举同样建议使用此方式定义）;

B.除了头文件或编译开关等特殊标识定义，宏定义不能使用下划线„_‟开头和结尾。

4.变量

原则：

A.一个变量只有一个功能，不能把一个变量用作多种用途;

B.结构功能单一；不要设计面面俱到的数据结构;

C.不用或者少用全局变量。

规则：

A.防止局部变量与全局变量同名;

B.通讯过程中使用的结构，必须注意字节序;

C.严禁使用未经初始化的变量作为右值;

建议：

A.构造仅有一个模块或函数可以修改、创建，而其余有关模块或函数只访问的全局变量，防止多个不同模块或函数都可以修改、创建同一全局变量的现象;

B.使用面向接口编程思想，通过API访问数据：如果本模块的数据需要对外部模块开放，应提供接口函数来设置、获取，同时注意全局数据的访问互斥;

C.在首次使用前初始化变量，初始化的地方离使用的地方越近越好;

D.明确全局变量的初始化顺序，避免跨模块的初始化依赖;

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

5.宏、常量

因为宏只是简单的代码替换，不会像函数一样先将参数计算后，再传递。

规则：

A.用宏定义表达式时，要使用完备的括号;

不规范：#define RECTANGLE_AREA(a, b) a * b

规范：#define RECTANGLE_AREA(a, b) ((a) * (b))

B.将宏所定义的多条表达式放在大括号中;

C.使用宏时，不允许参数发生变化;

#define SQUARE(a) ((a) * (a))

int a = 5;

int b;

不规范：

b = SQUARE(a++);

规范：

b = SQUARE(a);

a++;

建议：

A.除非必要，应尽可能使用函数代替宏;

B.常量建议使用const定义代替宏;

C.宏定义中尽量不使用return、 goto、 continue、 break等改变程序流程的语句。

6.注释

原则：

A.优秀的代码可以自我解释，不通过注释即可轻易读懂;

B.注释的内容要清楚、明了，含义准确，防止注释二义性;

C.在代码的功能、意图层次上进行注释，即注释解释代码难以直接表达的意图，而不是重复描述代码。

规则：

A.修改代码时，维护代码周边的所有注释，以保证注释与代码的一致性。不再有用的注释要删;

B.文件头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者姓名、工号、内容、功能说明、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明;

C.函数声明处注释描述函数功能、性能及用法，包括输入和输出参数、函数返回值、可重入的要求等；定义处详细描述函数功能和实现要点，如实现的简要步骤、实现的理由、 设计约束等;

D.全局变量要有较详细的注释，包括对其功能、取值范围以及存取时注意事项等的说明;

E.注释应放在其代码上方相邻位置或右方，不可放在下面。 如放于上方则需与其上面的代码用空行隔开，且与下方代码缩进相同;

F.避免在注释中使用缩写，除非是业界通用或子系统内标准化的缩写;

G.同一产品或项目组统一注释风格。

建议：

A.避免在一行代码或表达式的中间插入注释;

B.文件头、函数头、全局常量变量、类型定义的注释格式采用工具可识别的格式。

7.排版与格式

规则：

A.程序块采用缩进风格编写， 每级缩进为4个空格;

B.相对独立的程序块之间、变量说明之后必须加空行;

C.一条语句不能过长，如不能拆分需要分行写。一行到底多少字符换行比较合适，产品可以自行确定;

D.多个短语句（包括赋值语句）不允许写在同一行内，即一行只写一条语句;

E.if、 for、 do、 while、 case、 switch、 default等语句独占一行;

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

G.注释符（包括„/*‟„//‟„*/‟）与注释内容之间要用一个空格进行分隔。