一、嵌入式开发中值得注意的几个问题？

入职了新公司，最近几天在逐渐熟悉工作环境。总体的感觉还是可以的，硬件配置方面，工位很宽敞、双显示器，这大大地提高了我的工作效率。软件开发的氛围也很不错：

第一点是有严格地进行代码版本控制，版本控制对于我们软件方面的工作来说是非常重要的，否则一旦代码丢失，对于个人层面，那就做了很多无用功，对于公司层面，可能会错过产品上市的最佳时期。

第二点是有严格的一套项目软件设计方法，项目前期的准备工作非常重要，前期工作准备得越好项目的实施工作越好进行，否则可能就会在项目实施的过程中产生很多不可预测的问题，比如项目代码方面，想到什么功能就添加什么功能，这就会导致代码很混乱，因为有些功能之间的关联性很强。

很多外行对于软件行业的工作都以为是没日没夜地码代码，其实我们更多的时间、精力是在思考探索项目的实施方案，明确了整体方案的大体思路及重要的细节之后，才进行编码工作。

第三点是对于日常遇到的问题及解决方法要编写成文档输出，我觉得写——这一项能力是我们（不只是开发行业，各行各业都需要吧）必备的一项特别重要的技能，因为写的过程可以促使我们去思考去总结去查阅资料，最后的产出也方便日后的查阅，或多或少都会有一些收获。

不善于表达、不善于写作的我，想方设法地逼自己去写东西，因为这一项能力真的很重要，这也是我创建这个公众号的原因之一，现在也还是很差。如果对于写——这方面你也有所欠缺的话，建议你也可以去写一些博客，锻炼锻炼。

第四点是代码检查（Code Review）。以前，编程经验不足的我们常常是写完代码之后，编译没报错，管它三七二十一，先运行再说。但是，编写嵌入式程序，需要烧写程序，项目稍微大一点的，烧写就会很久，所以尽量减少烧写的次数，这就得好好的检查代码了，这也是有方法的，这个之后再做分享。

第五点是代码的编码规范，这也是本次要分享的主题。软件相关行业，都会涉及到协作开发，这就得遵守一些编程规范了，不然几个不一样风格的人写出来的代码最后归档为一份的时候就会很不协调，不便于管理与维护。每一种语言都有一些约定俗成的编程规范，这里，我们分享的是C语言的一些常见的编码规范。

综上，日常嵌入式软件开发中值得注意的几个问题是：

1、代码版本管理（代码备份）。

2、不要着急写代码，先分析项目整体流程及重要细节。

3、多记录一些自己遇到的问题及其解决方法。

4、写完代码应认真检查是不是有明显错误。

5、严格遵守常见的编码规范。

二、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） 防止把没有关联的语句放到一个函数中。

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

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