代码编程规范之注释风格

前言

这篇重点介绍一下代码编程的注释风格和注释文档生成工具

注释的原则是有助于对程序的阅读理解以及提供二次开发所需文档，注释的方式有很多，但是业内常用的规范是 Doxygen 代码注释规范。遵循原则为，说明性文件、函数接口必须充分注释说明。全局变量需要说明功能及取值范围，需要自行处理资料函数需要加上使用警告信息。

注意：

1. 不要使用注释来屏蔽代码。
2. 关于函数和局部变量的注释，当代码已经可自注释时，不用添加多余的注释。

简介

Doxygen 规范简要的说，Doxygen 注释块其实就是在C、C++注释块的基础添加一些额外标识，使 Doxygen 把它识别出来, 并将它通过对应得工具生成的说明文档。

文件注释

文件注释通常放在整个文件开头，如说明文件名、作者、日期、描述或版本等诸多信息，具体参数 Doxygen 的文件注释风格。

1/**
 2 * @file      文件名
 3 * @brief     简介
 4 * @details   细节
 5 * @mainpage  工程概览
 6 * @author    作者
 7 * @email     邮箱
 8 * @version   版本号
 9 * @date      年-月-日
10 * @license   版权
11 */

我常用的风格如下：

1/**
 2  **********************************************************************************************************************
 3  * @file    adcDrive.c
 4  * @author  const-zpc
 5  * @date    2020-7-20
 6  * @brief   该文件提供ADC驱动功能，以管理ADC驱动的以下功能：
 7  *           + 初始化
 8  *           + ADC数据
 9  *
10  **********************************************************************************************************************
11  * @attention
12  * 暂无
13  *
14  **********************************************************************************************************************
15  */

---

类/结构体注释

类或者结构体定义的注释方式非常简单，使用@brief后面填写类的概述，换行填写类的详细信息

/**
 * @brief   CAN发送帧类型结构体定义.
 */
typedef struct {
    uint32_t id;      /*!< 帧的标识符ID */
    CAN_IdTypeDef emIdType;/*!< 帧的类型 */
    CAN_RtrTypeDef emRtrType;/*!< 帧的格式 */
    uint8_t lenth;      /*!< 帧的数据长度 */
    uint8_t data[8];   /*!< 帧的数据内容 */
} CAN_TxFrameType;

---

枚举注释

/**
  * @brief  CAN使能/禁止枚举定义
  */
typedef enum{
    CAN_DISABLE = 0,      /*!< (0)禁止 */
    CAN_ENABLE = !CAN_DISABLE/*!< (1)使能 */
}CAN_EnableTypeDef;

/**
 * @brief   CAN帧的格式枚举定义.
 */
typedef enum {
    CAN_DATA_FRAME = 0,  /*!< (0)数据帧 */
    CAN_REMOTE_FRAME   /*!< (1)远程帧 */
} CAN_RtrTypeDef;

---

函数

1/**
 2  * @brief      读取指定CAN接收帧的数据信息.
 3  *
 4  * @note       建议先调用函数...
 5  * @param[in]  rxIndex g_arrtCANRxFrameInfo 的索引值
 6  * @param[in,out] pData - CAN帧数据内容指针.
 7  * @param[out] pLength - CAN帧数据长度.
 8  * @retval     数据长度
 9  */
10int CAN_ReadRxFrameInfo(uint16_t rxIndex, uint8_t *pData, uint8_t *pLength)
11{
12    ...
13}

文档生成软件

Doxygen 能将程序中的特定批注转换成为说明文档。他可以依据程序本身的结构，将程序中按规范注释的批注经过处理生成一个纯粹的参考手册，通过提取代码结构或借助自动生成的包含依赖图、继承图以及协作图来可视化文档之间的关系，Doxygen生成的帮助文档的格式可以是 CHM、RTF、PostScript、PDF、HTML等。

Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持 C、C++、Java、Objective-C 和 IDL 语言，部分支持 PHP、C#。注释的语法与 Qt-Doc、Kdoc 和 JavaDoc 兼容。Doxygen 可以从一套归档源文件开始，生成HTML格式的在线类浏览器，或离线LATE、RTF参考手册。

软件截图

根据上述定义的注释通过工具生成文档部分截图：