目录

前言

第1章 文件

1.1 头文件

1.2 定义文件

第2章 注释规范

2.1 共性注释规范

2.2 文档注释规范

2.3 C语言风格注释规范

第3章 排版规范

3.1 缩进与对齐 风格

3.2 空行

3.3 代码行

3.4 代码行内的空格

3.5 长行拆分

第4章 标识符命名规范

4.1 共性命名规则

4.2 文件命名规则

4.3 变量命名规则

4.4 函数命名规则

4.5 宏的命名规则

第5章 变量

第6章 常量、宏

第7章 数据类型

附件1 常用单词缩写（英文）（元音：aeiou）

附件2 常用反义词组（英文）

附件3 Doxygen格式常用关键字表

附件4 标识符命名个人风格

附件5 常见标识符命名风格种类

---

前言

        本编程规范是个人工作十几年来，近些年形成较为稳定的版本，已被工作的公司采纳为公司编程规范！本规范主要借鉴了一些大公司（华为，百度，腾讯，阿里巴巴，谷歌，苹果，微软，ARM，ST.....）的编程规范和风格，吸收它们的共性和个别优秀的地方。在一些细节方面请教了一些几十年的老工程师和一些华为等大公司软件工程师！

       本人曾创造过自己的编程风格，也曾想创造出世界上最完美的编程规范和风格，在当时的技术水平和行业局限下，自我感觉还是挺好的！随着经验的丰富，接触的技术越来越多，发现当初的一些规则和适用的环境已不再适用，甚至有些鸡肋，还增加了负担！在这方面也耗费很多没有价值的时间！后来痛定思痛改变编程规范和风格。不再原创，要与世界接轨，用符合当下所处大行业较为流行的，大公司通用的、大公司个别优秀的风格规范作为自己的编程规范和风格，简单说就是吸收大家之长处和共性，这样换了工作也能适用，新人进入也能快速适应，因为这些大多数人的规范和风格，少数服从多数。

        不要试图去创造最完美的编程规范和风格，每种风格都有长处和短处，这些不是我们的工作重心！编程规范和风格是为了给人看的，方便人们交流和阅读，每个人的喜欢都不同，很难满足和统一，如同世界很难统一一样。做到求同存异，兼容并包就可以了！编程规范和风格好与坏对芯片来说都一样，最终都要被翻译成机器码的！

第1章 文件

        每个 C++/C 程序通常分为两个文件。一个文件用于保存程序的声明（declaration），称为头文件。另一个文件用于保存程序的实现（implementation），称为定义（definition）文件。

        C++/C 程序的头文件以“.h”为后缀，C 程序的定义文件以“.c”为后缀，C++程序的定义文件通常以“.cpp”为后缀（也有一些系统以“.cc”或“.cxx”为后缀）。

1.1 头文件

        对于C语言来说，头文件的设计体现了大部分的系统设计。不合理的头文件布局是编译时间过长的根因。头文件主要由三部分内容组成：头文件注释；预处理块；函数声明等。

        通过头文件来调用库功能。在很多场合，源代码不便（或不准）向用户公布，只要向用户提供头文件和二进制的库即可。用户只需要按照头文件中的接口声明来调用库功能，而不必关心接口怎么实现的。编译器会从库中提取相应的代码。

        某产品曾经做过一个实验，把所有函数的实现通过工具注释掉，其编译时间只减少了不到10%，究其原因，在于A包含B，B包含C，C包含D，最终几乎每一个源文件都包含了项目组所有的头文件，从而导致绝大部分编译时间都花在解析头文件上。

        某产品更有一个“优秀实践”，用于将.c文件通过工具合并成一个比较大的.c文件，从而大幅度提高编译效率。其根本原因还是在于通过合并.c文件减少了头文件解析次数。但是，这样的“优秀实践”是对合理划分.c文件的一种破坏。

        大部分产品修改一处代码，都得需要编译整个工程，对于TDD之类的实践，要求对于模块级别的编译时间控制在秒级，即使使用分布式编译也难以实现，最终仍然需要合理的划分头文件、以及头文件之间的包含关系，从根本上降低编译时间。

    《google C++ Style Guide》1.2 头文件依赖 章节也给出了类似的阐述：若包含了头文件aa.h，则就引入了新的依赖：一旦aa.h被修改，任何直接和间接包含aa.h代码都会被重新编译。如果aa.h又包含了其他头文件如bb.h，那么bb.h的任何改变都将导致所有包含了aa.h的代码被重新编译，在敏捷开发方式下，代码会被频繁构建，漫长的编译时间将极大的阻碍频繁构建。因此，我们倾向于减少包含头文件，尤其是在头文件中包含头文件，以控制改动代码后的编译时间。

合理的头文件划分体现了系统设计的思想，但是从编程规范的角度看，仍然有一些通用的方法，用来合理规划头文件。本章节介绍的一些方法，对于合理规划头文件会有一定的帮助。

原则1.1.1  头文件适合放置对外接口的声明，不适合放置实现，实现应放在定义文件中。

说明：头文件是模块(Module)或单元(Unit)的对外接口。变量定义应在.c中定义，在.h中仅声明，尽量不要使用全局变量作为接口，变量是程序内部实现细节，应通过函数接口的方式对外暴露。

个人理解如下：

h文件：包含需用头文件、对外类型和枚举、对外宏(常量)定义、对外变量声明（尽量不用）、对外函数声明。

c文件：包含同名头文件、内部类型和枚举、内部宏(常量)定义、内部变量定义、内部函数定义与实现。
延伸阅读材料：《C语言接口与实现》（David R. Hanson 著 傅蓉 周鹏 张昆琪 权威 译 机械工业出版社 2004年1月）（英文版： "C Interfaces and Implementations"）

原则1.1.2  头文件应当职责单一。

说明：头文件过于复杂，依赖过于复杂是导致编译时间过长的主要原因。很多现有代码中头文件过大，职责过多，再加上循环依赖的问题，可能导致为了在.c中使用一个宏，而包含十几个头文件。

例如: 如下是某平台定义WORD类型的头文件：

#include <VXWORKS.H>
 
#include <STDIO.H>
 
#include <STDLIB.H>
 
#include <SYSLIB.H>
 
…
 
typedef unsigned short WORD;
 
…

        这个头文件不但定义了基本数据类型WORD，还包含了stdio.h syslib.h等等不常用的头文件。如果工程中有10000个源文件，而其中100个源文件使用了stdio.h的printf，由于上述头文件的职责过于庞大，而WORD又是每一个文件必须包含的，从而导致stdio.h/syslib.h等可能被不必要的展开了9900次，大大增加了工程的编译时间。

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

规则1.1.2  禁止头文件循环依赖。

说明：头文件循环依赖，是指a.h包含b.h，b.h包含c.h，c.h包含a.h之类。

规则1.1.3  头文件应当自包含。

说明：自包含是指任意一个头文件均可独立编译。如果a文件用到b文件内容，本应该a文件包含b.h头文件即可，但要包含b.h头文件前还要先包含c.h头文件才能工作的话，增添不必要的负担。

例如: a文件用到b文件内容

#include "c.h" //要想用b文件,a文件必须先包含c.h文件，这种情况就不是自包含。
#include "b.h" //a文件本应该包含b.h就可以。

规则1.1.4  .c/.h文件禁止包含用不到的头文件。

规则1.1.5  用#include <filename.h> 格式来引用标准库的头文件（编译器将从标准库目录开始搜索）。

规则1.2.6  用#include“filename.h”格式来引用非标准库的头文件（编译器将从用户工作目录开始搜索）。

规则1.1.7  为防止头文件被重复引用，应用ifndef/define/endif 结构产生预处理。命名格式：FILENAME_H_。

说明：没有在宏最前面加上“_"，是因为一般以"_"和”__"开头的标识符为系统保留或者标准库使用，在有些静态检查工具中，若全局可见的标识符以"_"开头会给出告警。后面加"_"是为了与程序用的宏定义区别。

例如：

#idndef LED_H_ //很明显这一部分也是为了防止重复引用
 
#define LED_H_
 
……
 
#endif /* LED_H_ */

规则1.1.8  禁止在头文件中定义变量。

说明：在头文件中定义变量，将会由于头文件被其他.c文件包含而导致变量重复定义。

规则1.1.9   禁止在extern "C"中包含头文件。（来自华为编程规范）

说明：在extern "C"中包含头文件，会导致extern "C"嵌套，Visual Studio对extern "C"嵌套层次有限制，嵌套层次太多会编译错误。在extern "C"中包含头文件，可能会导致被包含头文件的原有意图遭到破坏。

错误示例：

extern “C”
{
#include “xxx.h”
...
}

正确示例：

#include “xxx.h”
extern “C”
{
...
}

建议1.1.1  C程序头文件中加extern "C"。

说明：extern "C"的主要作用就是为了能够正确实现C++代码调用其他C语言代码。加上extern "C"后，会指示编译器这部分代码按C语言（而不是C++）的方式进行编译。由于C++支持函数重载，因此编译器编译函数的过程中会将函数的参数类型也加到编译后的代码中，而不仅仅是函数名；而C语言并不支持函数重载，因此编译C语言代码的函数时不会带上函数的参数类型，一般只包括函数名。

示例：  led头文件

#ifndef LED_H_ //很明显这一部分也是为了防止重复引用
#define LED_H_
 
#include"xxxx.h"
 
#ifdef __cplusplus //C++编译环境中（cpp文件定义了）定义了宏__cplusplus (plus plus就是"+ +"的意思)
extern "C"{ // 声明括号内是C语言代码，告诉C++编译器用C语言进行编译，这样C++就可以调用C头文件了
#endif
 
… //其他代码
 
#ifdef __cplusplus
}
#endif
 
#endif  /* LED_H_ */

建议1.2.2  头文件中只存放“声明”而不存放“定义”。

建议1.2.3  不提倡使用全局变量，尽量不要在头文件中出现象 extern int value 这类声明。

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

说明：需要注意的是，这个.h并不是简单的包含所有内部的.h，它是为了模块使用者的方便，对外整体提供的模块接口。

建议1.2.5  如果一个模块包含多个子模块，则建议每一个子模块提供一个对外的.h，文件名为子模块名。

说明：降低接口使用者的编写难度。

建议1.2.6  同一产品统一包含头文件排列方式。

说明：常见的包含头文件排列方式：功能块排序、文件名升序、稳定度排序。建议以稳定度排序。

#include <C标准库头文件>
#include <C++标准库头文件>
#include "平台头文件" //MCU厂家、系统等头文件
#include "第三方头文件" //公司或第三方提供的成熟头文件
#include "自己写的基础全局头文件"
          //base.h基础头文件，提供常用的数据类型、修饰符以及基础操作宏
          //global.h包含了其他基础的应用的头文件，第一个文件包含在应用相关c文件中。
 
#include "自己写的工具头文件"
#include "本项目头文件"
#include "本文头文件"

  

1.2 定义文件

        定义文件主要由三部分内容：定义文件注释；头文件的引用；程序的实现体（包括数据和代码）。

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

        代码的有效组织包括：逻辑层和物理层两个方面。逻辑层，主要是把不同功能的函数通过某种联系组织起来，主要关注模块间的接口，也就是模块的架构。物理层，无论使用什么样的目录或者名字空间等，需要把函数用一种标准的方法组织起来。例如：设计良好的目录结构、函数名字、文件组织等，这样可以方便查找。

原则1.2.1  一个函数仅完成一件功能。

说明：一个函数实现多个功能给开发、使用、维护都带来很大的困难。

原则1.2.2  重复代码应该尽可能提炼成函数。

说明：重复代码提炼成函数可以带来维护成本的降低。

规则1.2.1  避免函数过长，新增函数不超过50行（非空非注释行）。

说明：本规则仅对新增函数做要求，对已有函数修改时，建议不增加代码行。

规则1.2.2  避免函数的代码块嵌套过深，新增函数的代码块嵌套不超过4层。

说明：本规则仅对新增函数做要求，对已有的代码建议不增加嵌套层次。

规则1.2.3  设计高扇入，合理扇出（小于7）的函数。

说明：扇出是指一个函数直接调用（控制）其它函数的数目，而扇入是指有多少上级函数调用它。扇出过大，表明函数过分复杂，需要控制和协调过多的下级函数；而扇出过小，例如：总是1，表明函数的调用层次可能过多，这样不利于程序阅读和函数结构的分析，并且程序运行时会对系统资源如堆栈空间等造成压力。通常函数比较合理的扇出（调度函数除外）通常是3~5。

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

说明：可重入函数是指可能被多个任务并发调用的函数。在多任务操作系统中，函数具有可重入性是多个任务可以共用此函数的必要条件。共享变量指的全局变量和static变量。

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

建议1.2.1  函数不变参数使用const。

说明：不变的值更易于理解/跟踪和分析，把const作为默认选项，在编译时会对其进行检查，使代码更牢固/更安全。

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

建议1.2.3  检查函数所有非参数输入的有效性，如数据文件、公共变量等。

说明：函数的输入主要有两种：一种是参数输入；另一种是全局变量、数据文件的输入，即非参数输入。函数在使用输入参数之前，应进行有效性检查。

建议1.2.4  函数的参数个数不超过5个。

说明：函数的参数过多，会使得该函数易于受外部（其他部分的代码）变化的影响，从而影响维护工作。函数的参数过多同时也会增大测试的工作量。如果超过了5个建议拆分为不同函数。

建议1.2.5  除打印类函数外，不要使用可变长参函数。

说明：可变长参函数的处理过程比较复杂容易引入错误，而且性能也比较低，使用过多的可变长参函数将导致函数的维护难度大大增加。

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

说明：如果一个函数只是在同一文件中的其他地方调用，那么就用static声明。使用static确保只是在声明它的文件中是可见的，并且避免了和其他文件或库中的相同标识符发生混淆的可能性。

第2章 注释规范

        良好的注释可以提高程序的可读性、易防错性、易维护性等。

2.1 共性注释规范

原则2.1.1  优秀的代码可以自我解释，不通过注释即可轻易读懂。

说明：优秀的代码不写注释也可轻易读懂，注释无法把糟糕的代码变好，需要很多注释来解释的代码往往存在坏味道，需要重构。

原则2.1.2  注释的内容要清楚、明了，含义准确，防止注释二义性。 

说明：错误的注释不但无益反而有害。

原则2.1.3  在代码的功能、意图层次上进行注释，提供有用、额外的信息。 

说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。 

示例：如下注释意义不大。 

/* if receive_flag is TRUE */
if (receive_flag)

而如下的注释则给出了额外有用的信息。 

/* if mtp receive a message from links */
if (receive_flag)

规则2.1.1  边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要删除。

规则2.1.2  避免在注释中使用缩写，除非是通用或标准的缩写。 

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

规则2.1.3  标识符命名中若使用特殊约定或缩写，则要有注释说明。

规则2.1.4  同一产品或项目组 注释格式统一。

规则2.1.5  注释应与其描述的代码相靠近。

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

说明：可使程序排版整齐，并方便注释的阅读与理解。

建议2.1.1  避免在一行代码或表达式的中间插入注释。 

说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。

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

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

2.2 文档注释规范

规则2.2.1  对于要生成帮助文档的注释，采用工具可识别的注释格式。风格要统一。注释字符长度≤80。

说明：采用工具可识别的注释格式，例如Doxygen格式，方便工具导出注释形成帮助文档。(常见工具：Doxygen，JavaDoc，……)

示例：单行注释格式 1 采用风格：/** …… */  或 ///……  放在代码上行，表示注释下行代码

单行注释格式 2 采用风格：/**< …… */ 或 ///<…… 放在代码后面，表示注释前面代码

多行块注释格式 采用风格：/**

……

*/

规则2.2.2  项目、文件、函数、全局变量、全局常量、全局类型定义的注释格式采用工具可识别格式。

规则2.2.3  文件注释必须列出：版权说明、首页标签、工程名称、作者、工号、源码文档路径、项目详细描述、功能描述、用法描述、固件更新记录等。

示例：以doxygen格式为例（Doxygen格式常用关键字表，见附件1），注释风格如下：

/** @copyright Copyright(c)2014-2011 XXXX Co.,Ltd. All rights reserved.
  ******************************************************************************
  * @mainpage   无人机固件程序
  * <table>
  * <tr><th>Project  <td>A600
  * <tr><th>Author   <td>缪某某(ID:123456)
  * <tr><th>Source   <td>D:\workspace\demo_project\examples\A600\A600-doxygen
  * </table>
  * @section    项目描述
  * 该无人机是主要应用于......
  *
  * @section    功能描述
  * -# 定高悬停
  * -# 路径规划飞行
  *
  * @section    用法描述
  * -# 用遥控器
  *
  * @section    固件更新记录
  * <table>
  * <tr><th>Date        <th>H_Version   <th>S_Version       <th>Author  <th>Description  </tr>
  * <tr><td>2018/08/17  <td>1.0         <td>S02010041808171 <td>lebo    <td>创建初始版本 </tr>
  * <tr><td>2019/06/24  <td>1.1         <td>S02010041906241 <td>lebo    <td>
  * -# 无
  * </tr>
  * </table>
  ******************************************************************************
  */

规则2.2.4  文件注释必须列出：版权说明、作者、工号、版本号、生成日期、概要内容、注解说明功能、注意事项、修改日志等。

示例：以doxygen格式为例，注释格式 风格如下：

/** @copyright  Copyright(c)2014-2011 XXXX Co.,Ltd. All rights reserved.
  ******************************************************************************
  * @mainpage   FreeRTOS实验
  * <table>
  * <tr><th>Project  <td>FreeRTOSDemo
  * <tr><th>Author   <td>匠在江湖(ID:1234)
  * <tr><th>Source   <td>F:\BaiduNetdiskWorkspace\Work\FreeRTOSDemo
  * </table>
  * @section    项目描述
  * - 类别1
  *     -# 情况1......
  *     -# 情况2......
  * - 类别2
  *     -# 情况1......
  *     -# 情况2......
  * @section    用法描述
  * 
  * @section    固件更新记录
  * <table>
  * <tr><th>Date        <th>H_Version   <th>S_Version       <th>Author(ID:xxxxxx)   <th>Description  </tr>
  * <tr><td>2018/08/17  <td>1.0         <td>S02010041808171 <td>匠在江湖(ID:1234)   <td>创建初始版本 </tr>
  * </table>
  ******************************************************************************
  */

规则2.2.5  函数注释必须列出：概要、参数、返回值等。根据实际情况增加相关项。

示例1：以doxygen格式为例，注释格式 风格如下：

/**
  ******************************************************************************
  * @brief   发送接收 模拟函数
  * @param   None
  * @retval  None
  * @note    
  ******************************************************************************
  */

示例2：

/**
  ******************************************************************************
  * @brief  xxx 函数
  * @param  None
  * @return 函数执行结果
  * - E_SUCCESS 成功
  * - E_FAIL 失败
  * @par 示例:
  * @code
  *    int ret = register_all(&data, len, RT_TYPE_T1)
  * @endcode
  * @see :: xx表  
  ******************************************************************************
  */

示例3：

/**
  ******************************************************************************
  * @brief  Register a User ADC Callback
  *         To be used instead of the weak predefined callback
  * @param  hadc Pointer to a ADC_HandleTypeDef structure that contains
  *         the configuration information for the specified ADC.
  * @param  CallbackID ID of the callback to be registered
  *         This parameter can be one of the following values:
  *          @arg @ref HAL_ADC_CONVERSION_COMPLETE_CB_ID      ADC conversion complete callback ID
  *          @arg @ref HAL_ADC_CONVERSION_HALF_CB_ID          ADC conversion complete callback ID
  *          @arg @ref HAL_ADC_LEVEL_OUT_OF_WINDOW_1_CB_ID    ADC analog watchdog 1 callback ID
  *          @arg @ref HAL_ADC_ERROR_CB_ID                    ADC error callback ID
  *          @arg @ref HAL_ADC_INJ_CONVERSION_COMPLETE_CB_ID  ADC group injected conversion complete callback ID
  *          @arg @ref HAL_ADC_MSPINIT_CB_ID                  ADC Msp Init callback ID
  *          @arg @ref HAL_ADC_MSPDEINIT_CB_ID                ADC Msp DeInit callback ID
  *          @arg @ref HAL_ADC_MSPINIT_CB_ID MspInit callback ID
  *          @arg @ref HAL_ADC_MSPDEINIT_CB_ID MspDeInit callback ID
  * @param  pCallback pointer to the Callback function
  * @retval HAL status
  ******************************************************************************
  */

示例4：

/**
  ******************************************************************************
  * @brief  Enables ADC, starts conversion of regular group and transfers result
  *         through DMA.
  *         Interruptions enabled in this function:
  *          - DMA transfer complete
  *          - DMA half transfer
  *          - overrun (if available)
  *         Each of these interruptions has its dedicated callback function.
  * @note   Case of multimode enabled (for devices with several ADCs): This
  *         function is for single-ADC mode only. For multimode, use the
  *         dedicated MultimodeStart function.
  * @param  hadc ADC handle
  * @param  pData The destination Buffer address.
  * @param  Length The length of data to be transferred from ADC peripheral to memory.
  * @retval None
  ******************************************************************************
  */

建议2.2.6  类型定义列出：类型名称、概要等。根据实际情况增加相关项。

示例1：以doxygen格式为例，注释格式 风格如下：

/** @enum BoolTypeE
  * @brief 布尔类型（逻辑型变量的定义符）
  */
typedef enum
{
    E_FALSE = 0, //假（错误）
    E_TRUE = !E_FALSE //真（正确）
}BoolTypeE;

示例2：以doxygen格式为例，注释格式 风格如下：

/** @struct info
  * @brief 信息结构体 \n
  * 定义存储的信息
  */
typedef struct 结构体名字
{
   成员1, ///< 简要说明文字， 如果不加< 则会认为是成员2的注释
   成员2, ///< 简要说明文字
   成员3, ///< 简要说明文字
}结构体别名;

建议2.2.7  模块定义：模块组号 + 模块组名等。根据实际情况增加相关项。

示例1：纯定义。模块组号 MCU_Driver, 模块名 MCU Driver

/**
  * @defgroup MCU_Driver MCU Driver
  */
 
或
 
/**  @defgroup MCU_Driver MCU Driver */

示例2：定义 + 概要描述。

/** @defgroup MCU_Driver MCU Driver
  * @brief
  */

示例3：定义 + 组范围。

/** @defgroup MCU_Driver MCU Driver
  * @{
  */
 
......
 
/** @} end of MCU_Driver */

示例3：定义 + 组范围，加入到 MCU_Driver 模块组中，成为其子组。

/** @defgroup ADC_C_Includes ADC.C Includes
  * @ingroup  MCU_Driver
  * @{
  */
 
#include "base.h"
#include "adc.h"
 
/** @} end of ADC_C_Includes */

2.3 C语言风格注释规范

规则2.3.1  不用生成注释文档 的注释， 采用编程语言标准注释格式。风格要统一。注释字符长度≤80。

示例：多行或单行注释格式 采用风格：/* …… */

只可单行注释格式 采用风格：//…… 

建议2.3.1  包含头文件，类型定义，常量定义，宏定义，变量定义，函数定义与声明 要用注释划分模块，以便程序清晰易读。

建议2.3.2  定义文件中 包含头文件，类型定义，宏定义，变量定义，函数定义 注释风格。

/** @copyright  Copyright(c)2014-2011 XXXX Co.,Ltd. All rights reserved.
  ******************************************************************************
  * @file       mcu.c
  * @brief      
  * @details    
  * @author     匠在江湖(ID:1234)
  * @version    V1.0
  * @date       2014/05/08
  ******************************************************************************
  * @attention
  * 
  * @par 修改日志:
  * <table>
  * <tr><th>Date        <th>Version <th>Author(ID:xxxxxx)   <th>Description</tr>
  * <tr><td>2014/05/08  <td>V1.0    <td>匠在江湖(ID:1234)   <td>创建初始版本</tr>
  * </table>
  ******************************************************************************
  */
 
 
/* Includes *******************************************************************/
……用户定义内容
/* Private typedef ************************************************************/
……用户定义内容
/* Private constants **********************************************************/
……用户定义内容
/* Private macro **************************************************************/
……用户定义内容
/* Private variables **********************************************************/
……用户定义内容
/* Private function prototypes ************************************************/
……用户定义内容
 
 
/**
  ******************************************************************************
  * @brief  MCU 初始化 函数
  * @param  None
  * @return None
  * @note   
  ******************************************************************************
  */
void MCU_Init(void)
{
 
}
 
/********************************* END OF FILE ********************************/

建议2.3.3  头文件中 包含头文件，类型定义，常量定义，宏定义，函数声明 注释风格。

/** @copyright  Copyright(c)2014-2011 XXXX Co.,Ltd. All rights reserved.
  ******************************************************************************
  * @file       mcu.h
  * @brief      与硬件相关的寄存器定义，包含头文件等。为了适用平台的转换
  * @details    
  * @author     匠在江湖(ID:1234)
  * @version    V1.0
  * @date       2014/05/08
  ******************************************************************************
  * @attention
  * 
  * @par 修改日志:
  * <table>
  * <tr><th>Date        <th>Version <th>Author(ID:xxxxxx)   <th>Description</tr>
  * <tr><td>2014/05/08  <td>V1.0    <td>匠在江湖(ID:1234)   <td>创建初始版本</tr>
  * </table>
  ******************************************************************************
  */
 
 
#ifndef MCU_H_
#define MCU_H_
/* Includes *******************************************************************/
#include "stm32f1xx.h"
#include "stm32f1xx_hal.h"
#include "main.h"
#include "usart.h"
#include "base.h"
#include "iwdg.h"
 
#ifdef __cplusplus
 extern "C"{
#endif
 
/* Exported types *************************************************************/
/* Exported constants *********************************************************/
/* Exported macro *************************************************************/
///NOP()
#define NOP()                       __NOP
///清看门狗
#define CLR_WDG()                   HAL_IWDG_Refresh(&hiwdg) //清看门狗
 
 
/* Exported functions *********************************************************/
void MCU_Init(void);
 
#ifdef __cplusplus
}
#endif
 
#endif /* MCU_H_ */
 
/********************************* END OF FILE ********************************/

建议2.3.4  在程序块的结束行右方加注释标记，以表明某程序块的结束。 

说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。 

示例：参见如下例子。 

if (...)
{
    // program code
 
    while (index < MAX_INDEX)
    {
        // program code
    } /* end of while (index < MAX_INDEX) */ // 指明该条while语句结束
 
    // program code
} /* end of if (...)*/ // 指明是哪条if语句结束 

第3章 排版规范

        良好的排版可以提高程序的可读性、易防错性、易维护性等。

3.1 缩进与对齐 风格

规则3.1.1  程序块要采用缩进风格编写，缩进的空格数为4个。 不轻易使用TAB键。

说明：编辑器可用TAB键代替空格时方可使用，否则程序会因缩进不同而变乱。

规则3.1.2  程序块的分界符（如C/C++语言的大括号‘{’和‘}’）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。{ }之内的代码块在‘{’右边数格处左对齐。

说明：在函数体的开始、类的定义、结构的定义、枚举的定义以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。 

示例：

​​​​​​​如下例子不符合规范。 
for (...) {
... // program code
}
 
应如下书写。 
for (...)
{
... // program code
}

3.2 空行

规则3.2.1  在每个类声明之后、每个函数定义结束之后都要加空行。

规则3.2.2  在一个函数体内，逻揖上密切相关的语句之间不加空行，其它地方应

加空行分隔。

3.3 代码行

规则3.3.1  不允许把多个短语句写在一行中，即一行只写一条语句。 

示例：

​​​​​​​如下例子不符合规范。 
rect.length = 0; rect.width = 0;
 
应如下书写 
rect.length = 0;
rect.width = 0;

规则3.3.2  if、for、do、while、case、switch、default等语句自占一行，且if、for、do、while等语句的执行语句部分无论多少都要加括号{}。 

示例：

​​​​​​​如下例子不符合规范。 
if (pUserCR == NULL) return;
 
应如下书写： 
if (pUserCR == NULL)
{
    return;
}

3.4 代码行内的空格

规则3.4.1  关键字之后要留空格。象const、virtual、inline、case 等关键字之后至少要留一个空格，否则无法辨析关键字。象if、for、while 等关键字之后应留一个空格再跟左括号‘（’，以突出关键字。

规则3.4.2  函数名之后不要留空格，紧跟左括号‘（’，以与关键字区别。

规则3.4.3  ‘（’向后紧跟，‘）’、‘，’、‘;’向前紧跟，紧跟处不留空格。

规则3.4.4  ‘，’之后要留空格，如Function(x, y, z)。如果‘;’不是一行的结束符号，其后要留空格，如for (initialization; condition; update)。

规则3.4.5  赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”,“^”等二元操作符的前后应当加空格。

规则3.4.6  一元操作符如“!”、“~”、“++”、“--”、“&”（地址运算符）等前后不加空格。

规则3.4.7  像“［］”、“.”、“->”这类操作符前后不加空格。

建议3.4.1  对于表达式比较长的for 语句和if 语句，为了紧凑起见可以适当地去掉一些空格，如for (i=0; i<10; i++)和if ((a<=b) && (c<=d))

建议3.4.2  代码或注释结束后不要有多余的空格，防止空格后面有未知东西。

如下会存在未知隐患

应该如下

3.5 长行拆分

规则3.5.1  代码行不要过长，最长不超过80 个字符。否则眼睛看不过来，也不便于打印。

规则3.5.2  长表达式要在低优先级操作符处拆分成新行，操作符放在新行之首（以便突出操作符）。拆分出的新行要进行适当的缩进，使排版整齐，语句可读。

示例： 

if( (very_longer_variable1 >= very_longer_variable12)
 && (very_longer_variable3 <= very_longer_variable14)
 && (very_longer_variable5 <= very_longer_variable16))
{
    dosomething();
}

第4章 标识符命名规范

        规范的标识符命名可以提高程序的可读性、易防错性、易维护性等。标识符命名的种类繁多，各有优缺点。没有一种命名规则可以让所有的程序员赞同，程序设计教科书一般都不指定命名规则。命名规则对软件产品而言并不是“成败悠关”的事，我们不要化太多精力试图发明世界上最好的命名规则，而应当制定一种令大多数项目成员满意的命名规则，并在项目中贯彻实施。本章仅提出了大多都认可的规范，对于命名风格可依下面规范作为指导思想参考附件常见的风格。

4.1 共性命名规则

共性规则是被大多数程序员采纳的，我们应当在遵循这些共性规则的前提下，再扩充特定的规则。

原则4.1.1  标识符的命名要清晰、明了，有明确含义，使用完整的英文单词或大家基本可以理解的缩写，避免使人产生误解，让人快速理解你的代码很重要。

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

示例： temp缩写为tmp；flag缩写为flg；message缩写为msg。

规则4.1.1  产品/项目组内部应保持统一的命名风格。

说明：Unix like（小写下划线）和windows like（大小写混排）风格均有其支持者，产品应根据自己的部署平台，选择其中一种，并在产品内部保持一致。 不要使用大小写与下划线混排的方式，用作特殊标识如标识成员变量、全局变量或静态变量的m_、g_、s_，其后加上大小写混排的方式是允许的。

示例：Add_User不允许；add_user、AddUser、m_AddUser允许。

规则4.1.2  程序中不要出现仅靠大小写区分的相似的标识符。

示例：x 与 X 容易混淆。

建议4.1.1  用正确的反义词组命名具有互斥意义的变量或相反动作的函数等。

示例： min/max ……

建议4.1.2  尽量避免名字中出现数字编号，除非逻辑上的确需要编号。

示例：

​​​​​​​如下命名，使人产生疑惑。
#define _EXAMPLE_0_TEST_
 
应改为有意义的单词命名 
#define _EXAMPLE_UNIT_TEST_

建议4.1.3  标识符前不应添加模块、项目、产品、部门的名称作为前缀。

说明：很多已有代码中已经习惯在文件名中增加模块名，这种写法类似匈牙利命名法，导致文件名不可读，并且带来如下问题：第一眼看到的是模块名，而不是真正的文件功能，阻碍阅读；文件名太长；文件名和模块绑定，不利于维护和移植。若foo.c进行重构后，从a模块挪到b模块，若foo.c中有模块名，则需要将文件名从a_module_foo.c改为b_module_foo.c 。

建议4.1.4  平台/驱动等适配代码的标识符命名风格保持和平台/驱动一致。

说明：涉及到外购芯片以及配套的驱动，这部分的代码变动（包括为产品做适配的新增代码），应该保持原有的风格。

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

说明：根据源代码现有的风格继续编写代码，有利于保持总体一致。

4.2 文件命名规则

建议4.2.1  文件命名统一采用小写字符。

说明：因为不同系统对文件名大小写处理会不同（如MS的DOS、Windows系统不区分大小写，但是Linux系统则区分），所以代码文件命名建议统一采用全小写字母命名。

4.3 变量命名规则

规则4.3.1  全局变量应增加“g_”前缀。

规则4.3.2  静态变量应增加“s_”前缀。

说明：全局变量十分危险，增加前缀更加醒目，名字丑陋，促使开发人员小心和少使用。从根本上来说，尽量不使用全局变量。

规则4.3.3  禁止使用单个字符命名变量，但i、j、k作局部循环变量是允许的。

建议4.3.1  变量的名字应当使用“名词”或者“形容词＋名词”。

建议4.3.2  全局函数的名字应当使用“动词”或者“动词＋名词”（动宾词组）。类的成员函数应当只使用“动词”，被省略掉的名词就是对象本身。

4.4 函数命名规则

建议4.4.1  函数命名应以函数要执行的动作命名，一般采用动词或者动词+名词的结构。

建议4.4.2  函数指针除了前缀，其他按照函数的命名规则命名。

4.5 宏的命名规则

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

规则4.4.2 除了编译开关/头文件等特殊应用，应避免使用_EXAMPLE_TEST_之类以下划线开始和结尾的定义。

说明：一般来说，“_”开头、结尾的宏都是一些内部的定义，ISO/IEC 9899(俗称C99)中有描述。

第5章 变量

原则5.1.1 一个变量只有一个功能，不能把一个变量作多种用途。

原则5.1.2 结构单一，不要设计面面俱到的结构。

原则5.1.3 不用或者少用全局变量。

规则5.1.1 防止局部变量与全局变量重名。

规则5.1.2 通讯过程中使用的结构，必须注意字节序。

规则5.1.3 严禁使用未经初始化的变量作为右值

说明：在首次使用前初始化变量，初始化的地方离使用的地方越近越好，可以有效避免未初始化错误。

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

说明：降低全局变量耦合度。

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

建议5.1.3 明确全局变量初始化的顺序，避免跨模块初始化的依赖。

建议5.1.4 尽量减少没有必要的数据类型默认转换或强制转换。

第6章 常量、宏

规则6.1.1 用宏定义表达式时，要使用完备的括号。

说明：因为宏只是简单的代码替换，不会计算，存在一定的风险。

规则6.1.2 将宏定义的多条表达式放在大括号中。

说明：更好的方法是多条语句写成do while(0)的方式。

示例：

看下面的语句，只有宏的第一条表达式被执行。
#define FOO(x) \
    printf("arg is %d\n", x); \
    do_something_useful(x);
 
为了说明问题，下面for语句的书写稍不符规范
for (blah = 1; blah < 10; blah++)
FOO(blah)
 
用大括号定义的方式可以解决上面的问题：
#define FOO(x)    { \
                    printf("arg is %s\n", x); \
                    do_something_useful(x); \
                  }
 
但是如果有人这样调用：
if (condition == 1)
    FOO(10);
else
    FOO(20);
 
那么这个宏还是不能正常使用，所以必须这样定义才能避免各种问题：
#define FOO(x)      do{ \
                        printf("arg is %s\n", x); \
                        do_something_useful(x); \
                    }while(0)
 
用do-while(0)方式定义宏，完全不用担心使用者如何使用宏，也不用给使用者加什么约束。

规则6.1.3 使用宏时，不允许参数发生变化。

示例：

​​​​​​​如下用法可能导致错误。
#define  SQUARE(a) ((a)*(a))
int a=5;
int b;
b= SQUARE(a++);//结果：a=7,即执行了两次增。
 
正确用法：
b= SQUARE(a++);
a++；//结果：a=6,即执行了一次增。
 
同时也建议即使函数调用，也不要在参数中做变量变化操作，因为可能引用的接口函数，在某个版本升级后，变成了一个兼容老版本所做的一个宏，结果可能不可预知。

规则6.1.4 不允许直接使用魔鬼数字（没有具体含义的数字，字符串）。

说明：魔鬼数字含义不明确，维护难。使用常量定义魔鬼数字。0为特殊字符，没有歧义时，不用特别定义。

建议6.1.1 除非必要，应尽可能使用函数代替宏。

建议6.1.2 常量建议使用const定义代替宏。

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

建议6.1.4 常量后加后缀。32位常量要加ul。

U 或 u 无符号数

L 或 l 长整型

F 或 f 浮点数

第7章 数据类型

规则7.1.1 signed char和unsigned char用于数字型数据；char用于字符型数据。

说明：单纯的char所能接收的操作只有“ =、==、!= ”。

规则7.1.2 位域只能被定义为signed int和unsigned int。

说明：由于行为未被定义，所以不允许位域使用enum、short、char类型。

建议7.1.1 应使用指示了 大小 和 符号 的typedef以替代基本数据类型。

说明：不使用基本类型 char、int、short、long、float、double,而使用typedef创建别名体现大小和符号。

例如:32位计算机
typedef char                char_t;
typedef signed char         int8_t;
typedef unsigned char       uint8_t;
typedef signed short        int16_t;
typedef unsigned short      uint16_t;
typedef signed int          int32_t;
typedef unsigned int        uint32_t;
typedef signed long long    int64_t;
typedef unsigned long long  uint64_t;
typedef float               float32_t;
typedef double              float64_t;

附件1 常用单词缩写（英文）（元音：aeiou）

附件2 常用反义词组（英文）

附件3 Doxygen格式常用关键字表

附件4 标识符命名个人风格