嵌入式C语言编码规范

首先，借助本文的原作者–正点原子团队的左忠凯大神的一句话来开始：

之所以会写这份文档是要下定决心修改自己那写的跟一坨屎一样的垃圾代码规范！相信正在阅读本文档的读者出发点也是如此（可能你的代码规范还没有像一坨屎那么严重）

第一章 规范说明

因为作者工作内容的原因(做单片机开发板的)，此前没有代码规范化的思维，变量，函数的命名随心所欲，大小写混用；代码注释“//”和“/* */”混用等等很多陋习，这样的陋习写出的例程供阅读者学习也会带坏人家哒，所以痛定思痛，一定要改掉这些陋习。在这个看脸的时代，优美的代码风格让人看着都赏心悦目。 当然，代码规范和风格不是用来赏心悦目的，要不然就是花瓶了，代码规范和风格的目的是要编写出简洁明了、可维护、可测试、可靠、可移植、高效的代码。
1、简单、明了、清晰： 代码写出来重点是给人看的，因此简单、明了、清晰是第一要务！代码的可阅读性要高于代码的性能(除非你的代码以后不需要维护，那你写成啥样都无所谓)。简单、明了、清晰的代码也利于后期维护，尤其是当你写的代码交给他人去维护的时候，请不要祸害别人！

---

2、精简 代码越长越难看懂，这个大家应该都深有体会，一个1000多行的函数和一个最多100行的函数哪个好看？所以尽量将把函数写的精简。而且代码越长越容易出错，没有用的代码，变量等一定要及时的清理掉！功能类似或者重复的代码应尽可能提炼成一个函数。

---

3、尽量与原有代码风格保持一致 一个公司内部的代码风格一般都是统一的，但是如果你跳槽到其他公司去，或者有时候因为业务原因需要维护别的公司的代码，此时代码风格出现冲突的话尽可能使用现在维护的代码风格。

---

4、减少封装 此规则仅适用于作者所在公司，作者公司是做开发板的，所写的所有例程代码都需要开源给客户阅读学习。在编写的过程中会遇到使用很多第三方库，比如ST的HAL库、NXP的FSL库，LWIP协议栈、UCOS操作系统、FreeRTOS操作系统等等，这些第三方库的编码规范和风格各不相同。有人为了统一自己的编码风格会对这些第三方库的API函数做封装，如果是做产品的话这样做无可厚非，毕竟为了代码风格的统一，但是作为做开发板的，尽量不要对第三方库做封装！因为每一次封装都会将原有API函数的本意遮蔽，读者第一眼看懂这个API函数的具体函数，比如ST官方的Cube库里面就为了兼容自己的代码风格，对FreeRTOS的API函数做了封装，结果很多客户就问我们为何ST官方所调用的任务创建函数和我们的FreeRTOS教程不同！他们之间有什么区别？他们之间没有任何区别，只是ST对其做了一个简单的封装，结果给学习者带来了困惑！如果不做这个封装的话虽然影响到了代码风格的统一，但是却给学习者减少了困惑，提高了学习效率，而提高客户的学习效率是我们公司的第一宗旨！

---

第二章 排版格式和注释

排版是为了在编写代码的时候按照“一定的规矩”来编写，主要目的是为了是代码清晰、易于阅读。注释顾名思义就为注释自己的代码，以方便他人阅读，尤其是尤其维护人员。优美的排版和言简意赅的注释可以提高阅读者的阅读效率，所以在编写代码之前一定要确定好自己打算采用的排版方式和注释方式。

---

2.1 排版格式
2.1.1 代码缩进
代码缩进要使用制表符，也就是TAB键，不要使用空格键缩进！一般情况下一个TAB为4个字符，但是Linux建议TAB键为8个字符，因为8个字符缩进比较多，因为有利于长时间阅读代码，可以很清晰的分辨出多级嵌套，但是8个字符太多，代码向右移动的太远了，这样的话如果屏幕横向分辨率小的话每行编写的代码就会少，尤其是当一个代码块有多级缩进的时候，Linux建议你应该修改你的代码。这里我设置的TAB键为4个字符，因为在我阅读Linux内核源码的时候发现大部分都是4个字符。 在switch语句中，“swich”和“case”标签应该对齐处于同一列，不需要缩进case标签，如下所示：

2.1.3 代码行相关规范
1、 每一行的代码长度限制在80列。如果大于80列的话就要分成多行编写(其实当前高分辨屏幕已经很常见了，基本都是1080P起，甚至4K，所以可以设置更大值)，并且在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要适当进行缩进，一般进行一级缩进即可，如下所示：

2、不要把多个语句放到一行里面，一行只写一条语句，如下所示：

3、 不要在一行里面防止多个赋值语句。
4、if、for、do、while、case、swich、default等语句单独占用一行。

2.1.2 括号与空格
1、括号 代码中用到大括号“{”和“}”的地方，应该把起始大括号“{”放到行尾，把结束大括号“}”放到行首，如下所示：

上面大括号“{”和“}”的用法适用于所有的非函数程序块，如if、switch、for、do、while等，比如：

这里要注意！！！函数的起始大括号要放置到下一行的开头！！如下所示：

结束的大括号“}”要独自占用一行，除非后面跟着同一个语句的其它剩余部分，比如do语句中的“while”或者if语句中的“else”，如下代码所示：

和

当只有一个单独的语句的时候就可以不必要加大括号了，比如：

和

在上面的if else条件语句中，所有的分支都只有一行语句，所以可以都不加大括号。但是如果在条件语句中任何一个分支有大于一行语句的时候都必须加上大括号，如下所示代码：

---

2、空格
(1)、在一些关键字后面要添加空格，如：

但是不要在sizeof、typedof、alignof或者__attribute__这些关键字后面添加空格，因为这些大多数后面都会跟着小括号，因此看起来像个函数，如：

(2)、如果要定义指针类型，或者函数返回指针类型时，“”应该放到靠近变量名或者函数名的一侧，而不是类型名，如：

(3)、二元或者三元操作符两侧都要加一个空格，例如下面所示操作符：

(4)、一元操作符后不要加空格，如：

(5)、后缀自加或者自减的一元操作符前后都不加空格，如：

(6)、“.”和“->”这两个结构体成员操作符前后不加空格。
(7)、逗号、分号只在后面添加空格，如：

(8)、注释符“/”和“*/”与注释内容之间要添加一个空格。

---

2.2 注释
2.2.1 注释风格 注释可以让别人一看你的代码就明白其中的含义和用法，但是不要过度注释，**不要在注释里解释代码是任何运行的，一般你的注释应该告诉别人代码做了什么，而不是怎么做的，即结果，而非过程！**注释要放到函数的头部，尽量不要在函数体里面放置注释，注释的风格应该选择：

---

第三章 标识符命名

3.1 命名规则
C语言中的命名有多种风格，有unix风格的、有windows风格的、还有匈牙利命名法的等等。因为我们是编写Linux代码的，所以要使用unix风格，而Linux属于类unix系统。unix命名风格是单词用小写，然后每个单词用下划线“_”连接在一起，比如:read_adc1_value()，因此在函数和变量的命名上就要使用此种方法，这也是Linux内核里面所使用的命名方法。
注意事项：
1、命名一定要清晰！清晰是首位，要使用完整的单词或者大家都知道的缩写，让别人一读就懂，避免不必要的误会，比如：

2、除了常用的缩写以外，不要使用单词缩写，更不要用汉语拼音！！！
3、具有互斥意义的变量或者动作相反的函数应该是用互斥词组命名，如：

4、如果是移植的其它的代码，比如驱动，命名风格应该和原风格一致。
5、不要使用单字节命名变量，但是允许使用i，j，k这样的作为局部循环变量。

3.2 文件命名 文件统一采用小写命名。
3.3 变量命名
变量名一定要有意义，并且意义准确，单词都采用小写，用下划线“”连接。比如表示图书的数量的变量，就可以使用如下命名：

不要采用匈牙利命名法，尽量避免使用全局变量。
3.4 函数命名
和变量命名一样。
3.5 宏命名
对于数值等常量宏定义的命名，建议使用大写，单词之间使用下划线“”连接在一起，比如：

第四章 函数

函数要简短而且漂亮、并且只能完成一件事，函数的本地变量数量最好不超过5-10个，否则函数就有问题，需要重新构思函数，将其分为更小的函数，函数要注意的事项如下：
1、一个函数只能完成一个功能 如果一个函数实现多个功能的话将会给开发、使用和维护带来很大的困难。因此，在跟函数无关或者关联很弱的代码不要放到函数里面，否则的话会导致函数职责不明确，难以理解和修改。
2、重复代码提炼成函数 重复的代码给人的直观感受就是啰嗦，明明说一遍别人就能记住的事情，非要说好几遍！因此一定要消除重复代码，将其提炼成函数。
3、不同函数用空行隔开 不同的函数使用空行隔开，如果函数需要导出的话，它的EXPORT*宏应该紧贴在他的结束大括号下，比如：

4、函数集中退出方法 我们在学习C语言的时候都会听到或者看到这种说法：少用、最好不要用goto语句，但是linux源码中确大量的使用到了goto语句，linux源码使用goto语句来实现函数退出。当一个函数从多个位置推出，并且需要做一些清理的常见操作的时候，goto语句就很方便，如果不需要清理操作的话就直接使用return即可，如下所示：

5、函数嵌套不能过深，新增函数最好不超过4层 函数嵌套深度指的是函数中的代码控制块(例如：if、for、while、switch等)之间互相包含的深度，嵌套会增加阅读代码时候的脑力，嵌套太深非常不利于阅读！
6、对函数的参数做合法性检查 函数要对其参数做合法性的检查，比如参数如果有指针类型数据的话如果不做检查，当传入野指针的话就会出错。比如参数的范围不做检查的话可能会传递进来一个超出范围的参数值，导致函数计算溢出等。因此函数必须对参数做合法性检查，比如STM32的官方库函数就会对函数的参数做合法性的检查。
7、对函数的错误返回要做全面的处理 一个函数一般都会提供一些指示错误发生的方法，一般都用返回值来表示，因此我们必须对这些错误标识做处理。
8、源文件范围内定义和声明的函数，除非外部可见，否则都应该用static函数 如果一个函数只在同一个文件的其它地方调用，那么就应该用static，static确保这个函数只在声明它的文件是可见的，这样可以避免和其它库中相同标识符的函数或变量发生混淆。

第五章 变量

1、一个变量只能有一个功能，不能把一个变量当作多用途
一个变量只能有一个特定功能，不能把一个变量作为多用途使用，即一个变量取值不同的时候其代表的含义也不同，如：

2、不用或者少用全局变量 单个文件内可以使用static修饰的全局变量，这可以为文件的私有变量，全局变量应该是模块的私有数据，不能作用对外的接口，使用static类型的定义，可以防止外部文件对本文件的全局变量的非正常访问。直接访问其它模块的私有数据，会增强模块之间的耦合关系。
3、防止局部变量和全局变量重名 局部变量和全局变量重名会容易使人误解！
4、严禁使用未经初始化的变量作为右值 如果使用变量作为右值的话，在使用前一定要初始化变量，禁止使用未经初始化的变量作为右值，而且在首次使用前初始化变量的地方离使用的地方越近越好！未初始化变量是C和C++最常见的错误源，因此在变量首次使用前一定要确保正确初始化，如：


5、明确全局变量的初始化顺序 系统启动阶段，使用全局变量前，要考虑到全局变量该在什么地方初始化！使用全局变量和初始化全局变量之间的时序关系一定要分析清楚！
6、尽量减少不必要的数据类型转换 进行数据类型转换的时候，其数据的意义、转换后的取值等都有可能发生变化，因此尽量减少不必要的数据类型转换。

第六章 宏和常量