原创 嵌入式软件开发编程规范介绍

　　对于嵌入式系统来讲，嵌入式软件相当于嵌入式系统的灵魂，整个嵌入式系统如何工作，都是由嵌入式软件来控制的。如何编写高质量，高效率的嵌入式软件在实际项目开发过程中变的越来越重要。

　　相信大家都有过这样的感受：看到不规范（杂乱差）的代码，瞬间就没有看下去的欲望了。

　　嵌入式软件开发编程规范介绍

　　当我们在公司进行嵌入式项目开发的时候，并不是你一个人在单打独斗，通常是一个团队在一起战斗。很多人一起共同完成一个嵌入式项目，通常是每个成员，每个小组完成整个项目中的一个或几个模块。我们编写的代码首先是给人看的，其次才是给机器执行的，这就要求我们团队中的每个人在编写软件的时候，要遵循统一的编程规范和编码风格，提高代码的可读性和可维护性，方便团队成员之间的沟通和交流。在实际项目开发过程中，遵循统一的编程规范相当重要，同学们一定要引起足够的重视，下面我就从代码排版，代码注释，标识符命名，代码可读性和函数设计几个方面来讲解比较通用的嵌入式软件编程规范。

　　关于编程规范及原则Ⅱ

　　编程规范也就是编写出简洁、可维护、可靠、可测试、高效、可移植的代码，提高产品代码的质量。

　　本文针对嵌入式，主要结合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;

　　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.注释符（包括?/*??//??*/?）与注释内容之间要用一个空格进行分隔。

　　嵌入式编程中的注意事项

　　嵌入式软件开发和普通软件编程相比，有一些自己的特点，下面从嵌入式软件架构，中断编程，寄存器配置，浮点运算等几个方面来讲解嵌入式编程中的注意事项.

　　1. 嵌入式系统的软件架构

　　一个大型的嵌入式软件往往需要根据功能的不同划分成多个软件功能模块。

　　1) 模块即是一个.c文件和一个.h文件的结合，头文件(.h)中是对于该模块接口的声明;

　　2) 某模块提供给其它模块调用的外部函数及数据需在.h中文件中冠以extern关键字声明;

　　3) 模块内的函数和全局变量需在.c文件开头冠以static关键字声明;

　　4) 永远不要在.h文件中定义变量!定义变量和声明变量的区别在于定义会产生内存分配的操作，是汇编阶段的概念;而声明则只是告诉包含该声明的模块在连接阶段从其它模块寻找外部函数和变量

　　2. 中断编程

　　中断是嵌入式系统中重要的组成部分，但是在标准C中不包含中断。 许多编译开发商在标准C上增加了对中断的支持，提供新的关键字用于标示中断服务程序. 类似于__interrupt、#program interrupt等。当一个函数被定义为中断服务处理程序的时候，编译器会自动为该函数增加中断服务程序所需要的中断现场入栈和出栈代码。

　　中断服务程序需要满足如下要求：

　　1) 不能有返回值;

　　2) 不能向中断服务处理程序传递参数;

　　3) 中断服务处理程序应该尽可能的短小精悍，不要包含耗时的代码

　　3. 寄存器配置

　　嵌入式软件是面向硬件底层的软件，我们在对硬件进行编程时，通常是通过配置硬件相关的寄存器来实现的。在配置寄存器时，通常我们只需要配置寄存器的1位或几位，对于其他不需要配置的位，我们要保持不变，不要更改我们不需要配置的位。

　　例如：我们希望配置寄存器的　GPIOADAT 的第 1位 为 1

　　我们不能这样写成这样:

　　GPIOADAT = 0x02; //将其他位设置为 0

　　而应该写成这样:

　　GPIOADAT |= 0x02; //保证其他位不变

　　4. 浮点运算

　　大多数低档次的单片机都是不支持浮点运算的，因此在实际使用过程中也很少用到，因此为了降低成本，一般都去掉了浮点运算模块，这就带来了一个问题，如果万一要用到浮点运算怎么办?我们可以采用的是“定点”的方法来解决这个问题，就是直接放大10的N次方倍进行整数的计算，可以得出近似值，因此为了不增加不必要的麻烦，应该总是尽量避免使用浮点运算，一般情况也是可以避免的。

　　5. volatile 关键字的使用

　　嵌入式开发过程中，在定义硬件寄存器的时候，需要使用volatile关键字。 volatile提醒编译器它后面所定义的变量随时都有可能改变，因此编译后的程序每次需要存储或读取这个变量的时候，都会直接从变量地址中读取数据。 如果没有volatile关键字，则编译器可能优化读取和存储，可能暂时使用寄存器中的值。