0
  • 聊天消息
  • 系统消息
  • 评论与回复
登录后你可以
  • 下载海量资料
  • 学习在线课程
  • 观看技术视频
  • 写文章/发帖/加入社区
会员中心
创作中心

完善资料让更多小伙伴认识你,还能领取20积分哦,立即完善>

3天内不再提示

代码编程规范之注释风格

汽车电子技术 来源:大橙子疯嵌入式 作者: 大橙子疯 2023-02-15 15:01 次阅读

前言

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

注释的原则是有助于对程序的阅读理解以及提供二次开发所需文档,注释的方式有很多,但是业内常用的规范是 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参考手册。

软件截图

图片

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

图片

图片

图片图片图片

声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容侵权或者其他违规问题,请联系本站处理。 举报投诉
  • 代码
    +关注

    关注

    30

    文章

    4786

    浏览量

    68549
  • 注释
    +关注

    关注

    0

    文章

    11

    浏览量

    6528
  • 全局变量
    +关注

    关注

    1

    文章

    28

    浏览量

    8966
收藏 人收藏

    评论

    相关推荐

    MATLAB 编程风格指南

    thebeginning.”(良好的写作规范的程序比糟糕的写作规范的要好,因为他们具有较少的错误、易于调试与修改,因此,从一开始就考虑风格是很重要的)。本指南列举的MATLAB 代码
    发表于 09-22 16:19

    FPGA实战演练逻辑篇39:代码风格与书写规范

    代码风格与书写规范本文节选自特权同学的图书《FPGA设计实战演练(逻辑篇)》配套例程下载链接:http://pan.baidu.com/s/1pJ5bCtt 不同的人可能对代码
    发表于 06-19 10:38

    单片机开发C语言编程基本规范

    为了提高源程序的质量和可维护性,从而最终提高软件产品生产力,特编写此规范。本标准规定了程序设计人员进行程序设计时必须遵循的规范。本规范主要针对单片机编程语言和08编译器而言,包括排版、
    发表于 08-09 11:11

    单片机开发C语言编程基本规范

    、变量使用、代码可测性、程序效率、质量保证等内容。 1.基本规则 格式清晰、注释简明扼要、命名规范易懂、函数模块化、程序易读易维护、功能准确实现、代码空间效率和时间效率高、适度的可扩展
    发表于 09-20 16:39

    单片机开发C语言编程基本规范

    、变量使用、代码可测性、程序效率、质量保证等内容。 1.基本规则 格式清晰、注释简明扼要、命名规范易懂、函数模块化、程序易读易维护、功能准确实现、代码空间效率和时间效率高、适度的可扩展
    发表于 03-10 10:46

    单片机开发C语言编程基本规范

    规范主要针对单片机编程语言和08编译器而言,包括排版、注释、命名、变量使用、代码可测性、程序效率、质量保证等内容。 1.基本规则 格式清晰、注释
    发表于 08-06 09:46

    单片机开发C语言编程基本规范

    单片机开发C语言编程基本规范为了提高源程序的质量和可维护性,从而最终提高软件产品生产力,特编写此规范。本标准规定了程序设计人员进行程序设计时必须遵循的
    发表于 10-07 11:53

    单片机开发C语言编程基本规范

    、变量使用、代码可测性、程序效率、质量保证等内容。 1.基本规则 格式清晰、注释简明扼要、命名规范易懂、函数模块化、程序易读易维护、功能准确实现、代码空间效率和时间效率高、适度的可扩展
    发表于 10-14 10:23

    单片机开发C语言编程基本规范

    、变量使用、代码可测性、程序效率、质量保证等内容。 1.基本规则 格式清晰、注释简明扼要、命名规范易懂、函数模块化、程序易读易维护、功能准确实现、代码空间效率和时间效率高、适度的可扩展
    发表于 10-20 09:39

    [分享] 单片机开发C语言编程的基本规范

    规范主要针对单片机编程语言和08编译器而言,包括排版、注释、命名、变量使用、代码可测性、程序效率、质量保证等内容。 1.基本规则 格式清晰、注释
    发表于 04-08 08:00

    Linux内核编码风格(编程代码风格推荐)

    这是翻译版本,英文原版是linux源码Documentation文件夹下的CodingStyle一个良好风格的程序看起来直观、美观,便于阅读,还能有助于对程序的理解,特别在代码量比较大情况下更显
    发表于 08-24 09:45

    单片机程序设计编程规范分享

    严格,品质要求高的软件公司对员工编写代码风格都有硬性规定,例如缩排的使用,TAB 的长度,函数变量的命名方式. 这些规定的明显好处是可以统一规范不同程序员所编制的代码,提升程序
    发表于 09-25 08:06

    如何在代码中添加注释

    什么是代码注释,如何在代码中添加注释,相信每一位了解编程的人并不陌生。注释里往往有很多有趣的脑洞
    的头像 发表于 10-17 10:53 1.1w次阅读

    嵌入式代码编写规范

    嵌入式代码编码规范,用于规范自己的代码,增强可读性,非标准规范。最好能强制自己形成良好的编码风格
    的头像 发表于 04-26 15:21 5275次阅读

    代码编程规范命名规范

    标识符的命名规则历来是一个敏感话题,典型的命名风格如unix风格、windows风格等,从来无法达成共识。实际上,各种风格都有其优势也有其劣势,而且往往和个人的审美观有关。对标识符定义
    的头像 发表于 02-15 14:57 1356次阅读