嵌入式C语言编程规范

一、前言

刚开始学STM32的时候，看到一些比较规范的代码中的一些变量命名为ucValue 、g_ucPara等形式，当时觉得好不习惯，为什么要加uc、g_uc等，感觉好难看，后来才知道，这些前缀都有其约定俗成的意思，可以方便的知道变量的数据类型。

如：uc代表的是unsigned char，所以一个变量命名为ucValue就可以清楚的表明其为unsigned char的变量 。同样的，g代表global，即全局的，g_ucPara表明其为unsigned char类型的全局变量。

现在我们来看网上的一些比较权威的编码规范，比如安富莱的编码规范：

二、编程规范

1、文件与目录

（1）文件的命名

文件的命名要准确清晰地表达其内容，同时文件名应该精练，防止文件名过长而造成使用不便。在文件名中可以适当地使用缩写。 以下提供两种命名方式以供参考：

• 各程序模块的文件命名开头 2 个消协字母代表本模块的功能：

  如：主控程序为 mpMain.c，mpDisp.c 等。

• 不写模块功能标识：
  如：主控程序为 Main.c，Disp.c 等。

（2）头文件中段落安排顺序

// 1、文件头注释
// 2、防止重复引用头文件的设置
// 3、#include 部分
// 4、enum 常量声明
// 5、类型声明和定义，包括 struct、union、typedef 等
// 6、全局变量声明
// 7、文件级变量声明
// 8、全局或文件级函数声明
// 9、函数实现。按函数声明的顺序排列
// 10、文件尾注释

（3）在引用头文件时，不要使用绝对路径

如果使用绝对路径，当需要移动目录时，必须修改所有相关代码，繁琐且不安全；使用相对路径，当需要移动目录时，只需修改编译器的某个选项即可。例如：

#include “/project/inc/hello.h” /* 不应使用绝对路径 */
#include “../inc/hello.h”       /* 可以使用相对路径 */

（4）在引用头文件时 ，使用<>还是""

#include <stdio.h>      /* 标准头文件 */
#include <projdefs.h>   /* 工程指定目录头文件 */
#include “global.h”     /* 当前目录头文件 */
#include “inc/config.h” /* 路径相对于当前目录的头文件 */

（5）防止头文件被重复引用

#ifndef __DISP_H /* 文件名前名加两个下划线“__”，后面加 “_H”
#define __DISP_H
...
...
#endif

（6）头文件中只存放“声明”而不存放“定义”

（7）文件的长度

文件的长度没有非常严格的要求，但应尽量避免文件过长。一般来说，文件长度应尽量保持在 1000 行之内 。

2、排版

（1）程序块要采用缩进风格编写，缩进的空格数为 4 个。

（2）相对独立的程序块之间、变量说明之后必须加空行 。

（3） 较长的语句或函数过程参数（>80 字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。

（4） 不允许把多个短语句写在一行中，即一行只写一条语句

（5）程序块的分界符（如大括号‘{’和‘}’ ）应各独占一行并且位于同一列

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

示例：

• 逗号、分号只在后面加空格。

• 比较操作符，赋值操作符"="、 “+=”，算术操作符"+"、"%"，逻辑操作符"&&"、"&"，位域操作符"<<"、"^"等双目操作符的前后加空格。

• "!"、"~"、"++"、"–"、"&"（地址运算符）等单目操作符前后不加空格。

• "->"、"."前后不加空格。

• if、for、while、switch 等与后面的括号间应加空格，使 if 等关键字更为突出、明显，函数名与其后的括号之间不加空格，以与保留字区别开。

3、注释

（1） 一般情况下，源程序有效注释量必须在 20％以上。

说明：注释的原则是有助于对程序的阅读理解，在该加的地方都加，注释不宜太多也不能太少，注释语言必须准确、易懂、简洁 。

（2） 在文件的开始部分，应该给出关于文件版权、内容简介、修改历史等项目的说明。

在创建代码和每次更新代码时，都必须在文件的历史记录中标注版本号、日期、作者、更改说明等项目。 下面是一个范例，当然，并不局限于此格式，但上述信息建议要包含在内。

（3）对于函数，在函数实现之前，应该给出和函数的实现相关的足够而精练的注释信息。

示例：

下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

（4） 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。
（5） 注释的内容要清楚、明了，含义准确，防止注释二义性。

说明：错误的注释不但无益反而有害。注释主要阐述代码做了什么（What），或者如果有必要的话，阐述
为什么要这么做（Why），注释并不是用来阐述它究竟是如何实现算法（How）的。

（6） 避免在注释中使用缩写，特别是非常用缩写。

说明：在使用缩写时或之前，应对缩写进行必要的说明。

（7） 注释应与其描述的代码靠近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置，
不可放在下面，如放于上方则需与其上面的代码用空行隔开。

示例：如下例子不符合规范。

例 1：不规范的写法

例 2：不规范的写法

例 3：规范的写法

例 4：不规范的写法，显得代码过于紧凑

例 5：规范的写法

（8） 注释与所描述内容进行同样的缩排。

说明：可使程序排版整齐，并方便注释的阅读与理解。
例 1：如下例子，排版不整齐，阅读稍感不方便。

例 2：正确的布局。

（9） 对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计文档。

（10） 对于 switch 语句下的 case 语句，如果因为特殊情况需要处理完一个 case 后进入下一个 case 处理，必须在该 case 语句处理完、下一个 case 语句前加上明确的注释。

说明：这样比较清楚程序编写者的意图，有效防止无故遗漏 break 语句。

示例（注意斜体加粗部分）：

（11） 注释格式尽量统一，建议使用“/ …… /”，因为 C++注释“//”并不被所有 C 编译器支持。

（12） 注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能非常流利准确的用英文表达。

说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。

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

说明：较短的单词可通过去掉“元音”形成缩写；较长的单词可取单词的头几个字母形成缩写；一些单词有大家公认的缩写。
示例：如下单词的缩写能够被大家基本认可。

temp 可缩写为 tmp;
flag 可缩写为 flg;
statistic 可缩写为 stat;
increment 可缩写为 inc;
message 可缩写为 msg; 

（14） 命名中若使用特殊约定或缩写，则要有注释说明。
说明：应该在源文件的开始之处，对文件中所使用的缩写或约定，特别是特殊的缩写，进行必要的注释说明。

（15） 自己特有的命名风格，要自始至终保持一致，不可来回变化。
说明：个人的命名风格，在符合所在项目组或产品组的命名规则的前提下，才可使用。（即命名规则中没有规定到的地方才可有个人命名风格）

（16） 对于变量命名，禁止取单个字符（如 i、j、k…）

建议除了要有具体含义外，还能表明其变量类型、数据类型等，但 i、j、k 作局部循环变量是允许的。变量，尤其是局部变量，如果用单个字符表示，很容易敲错（如i写成j），而编译时又检查不出来，有可能为了这个小小的错误而花费大量的查错时间 。

（17） 命名规范必须与所使用的系统风格保持一致，并在同一项目中统一

比如采用 UNIX 的全小写加下划线的风格或大小写混排的方式，不要使用大小写与下划线混排的方式，用作特殊标识如标识成员变量或全局变量的 m_和 g_，其后加上大小写混排的方式是允许的。
示例： Add_User不允许，add_user、AddUser、m_AddUser允许。

（18） 除非必要，不要用数字或较奇怪的字符来定义标识符。
示例：如下命名，使人产生疑惑。

应改为有意义的单词命名：

4、可读性

（1） 注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。

（2） 避免使用不易理解的数字，用有意义的标识来替代。

示例：如下的程序可读性差

应改为如下形式 ：

（3） 不要使用难懂的技巧性很高的语句，除非很有必要时。

说明：高技巧语句不等于高效率的程序，实际上程序的效率关键在于算法。
示例：如下表达式，考虑不周就可能出问题，也较难理解。

应分别改为如下：

5、变量、 结构、 常量、 宏

（1） 为了方便书写及记忆，变量类型采用如下重定义：

（2） 常见类型的前缀

• 对于一些常见类型的变量，应在其名字前标注表示其类型的前缀。前缀用小写字母表示。前缀的使用请参照下列表格中说明。
  

（3） 变量作用域的前缀

为了清晰的标识变量的作用域，减少发生命名冲突，应该在变量类型前缀之前再加上表示变量作用域的前缀，并在变量类型前缀和变量作用域前缀之间用下划线 - 隔开。

具体的规则如下：

• 对于全局变量（global variable），在其名称前加g和变量类型符号前缀。

uint32_t g_ulParaWord;
uint8_t g_ucByte;

• 对于静态变量（static variable），在其名称前加s和变量类型符号前缀。

static uint32_t s_ulParaWord;
static uint8_t s_ucByte;

• 函数内部等局部变量前不加作用域前缀。
• 对于常量，当可能发生作用域和名字冲突问题时，以上几条规则对于常量同样适用。注意，虽然常量名的核心部分全部大写，但此时常量的前缀仍然用小写字母，以保持前缀的一致性。

（4） 结构体命名规则

表示类型的名字，所有名字以小写字母tag开头，之后每个英文单词的第一个字母大写（包括第一个单词的第一个字母），其他字母小写，结尾_T 标识。单词之间不使用下划线分隔,结构体变量以 t 开头。 如：

/* 结构体命名类型名 */
typedef struct tagBillQuery_T
{
...
}BillQuery_T;
/* 结构体变量定义 */
BillQuery_T tBillQuery;

（5）对于枚举定义全部采用大写，结尾_E 标识。

（6）常量、宏、模版的名字应该全部大写。如果这些名字由多个单词组成，则单词之间用下划线分隔。

#define LOG_BUF_SIZE 8000

6、函数

（1） 函数的命名规则。

每一个函数名前缀需包含模块名，模块名为小写，与函数名区别开。

如：uartReceive(串口接收)

备注：对于非常简单的程序，可以不加模块名。

（2）函数的形参。

函数的的形参都以下划线_开头，已示与普通变量进行区分，对于没有形参为空的函数(void)括号紧跟函数后面。

uint32_t uartConvUartBaud(uint32_t _ulBaud)

{

}

（3） 一个函数仅完成一件功能。

（4） 函数名应准确描述函数的功能，使用动宾词组为执行某操作的函数命名。

说明：避免用含义不清的动词如process、handle等为函数命名，因为这些动词并没有说明要具体做什么。

示例：参照如下方式命名函数。

（5）避免设计五个以上参数函数，不使用的参数从接口中去掉。

说明：目的减少函数间接口的复杂度，复杂的参数可以使用结构传递。

（6）在调用函数填写参数时，应尽量减少没有必要的默认数据类型转换或强制数据类型转换。
说明：因为数据类型转换或多或少存在危险。

（7） 防止把没有关联的语句放到一个函数中。

示例：如下函数就是一种随机内聚。

矩形的长、宽与点的坐标基本没有任何关系，故以上函数是随机内聚。应如下分为两个函数：

---

我的个人博客：https://zhengnianli.github.io/
我的微信公众号：嵌入式大杂烩