C/C++ 代码注释规范及 doxygen 工具

参考

谷歌项目风格指南------注释

C++ doxygen 风格注释示例

ubuntu20 中 doxygen 文档生成

doxygen 官方文档 在 /Doxygen/Special Command/ 章节介绍 doxygen 的关键字

注释说明

注释的目的是提高代码的可读性与可维护性。

C 风格注释

cpp 复制代码
// 单行注释

/*
多行注释
*/

C ++ 风格注释:

cpp 复制代码
/// 单行注释
//! 单行注释

/**
多行注释
*/
/*!
多行注释
*/
  • 文件注释:时间 + 版权 + 维护作者 + 文件内容

  • 类注释:类的功能 + 用法 + 注意事项

  • 函数注释:

    函数声明通常位于头文件,头文件是客户使用函数服务的窗口。在函数声明处需要注释函数功能,解释接口,调用规则,潜在风险等,以避免函数使用不当;

    函数定义通常位于源文件,源文件是程序员维护,实现功能的平台。比喻作平台是因为服务端功能实现可以是由多个程序员共同维护的,注释要注重功能理解以降低代码维护成本。在函数定义处需要注释功能实现细节,编程技巧,算法原理,详细文档资料位置等。

    不要重复函数声明和定义的注释,没有意义!

  • 变量注释:

    成员变量和局部变量:除了简单的变量,都要说明变量的定义和用途。尤其是定义解释至关重要,避免变量被滥用导致歧义!有特定值的变量需要强调特定值。

    全局变量:每个全局变量都要说明定义和用途。

  • 实现注释:对巧妙, 晦涩, 重要的地方加以注释。解释代码段功能或为什么这么处理。

  • TODO注释:对临时方案,不好的代码注释方便日后改进。

  • 弃用注释:在弃用代码上方加// deprecate:弃用说明。弃用代码最好用 // 屏蔽,方便搜索栏发现代码已弃用。

Utuntu20 Vscode Doxygen 自动生成文档

vscode 安装 doxygen documentation generator 插件,在插件的商店页面,点击导航栏的 Config options 可以跳转到 json 配置说明位置。

安装好插件后,在文件头和函数头部打/**回车,就会生成注释。

在 vscode 按 ctrl+shift+p,搜索 "settings",选择首选项配置(JSON)配置 doxygen 参数。

粘贴下面配置:

javascript 复制代码
    // ---------- doxygen 注释配置 ---------- start line

    "doxdocgen.c.triggerSequence": "/**", // 触发 doxygen 注释
    "doxdocgen.c.commentPrefix": " * ", // 中间注释行的前缀
    "doxdocgen.c.firstLine": "/**", // 注释首行
    "doxdocgen.c.lastLine": " */", // 注释尾行

    "doxdocgen.generic.authorName": "jucat",
    "doxdocgen.generic.authorEmail": "lmr2887@163.com",
    "doxdocgen.generic.authorTag": "@author {author} ({email})",
    "doxdocgen.generic.dateFormat": "YYYY-MM-DD",
    "doxdocgen.generic.dateTemplate": "@date {date}",
    "doxdocgen.generic.generateSmartText": false,
    "doxdocgen.generic.boolReturnsTrueFalse": true,
    "doxdocgen.generic.briefTemplate": "@brief {text}",
    "doxdocgen.generic.includeTypeAtReturn": true,
    "doxdocgen.generic.linesToGet": 20,
    "doxdocgen.generic.customTags": [],
    "doxdocgen.generic.paramTemplate": "@param {param} ",
    "doxdocgen.generic.returnTemplate": "@return {type} ",
    "doxdocgen.generic.splitCasingSmartText": true,
    "doxdocgen.generic.filteredKeywords": [],
    "doxdocgen.generic.useGitUserName": false,
    "doxdocgen.generic.useGitUserEmail": false,
    "doxdocgen.generic.commandSuggestion": true,
    "doxdocgen.generic.commandSuggestionAddPrefix": false,

    // 文件头部注释
    "doxdocgen.file.copyrightTag": ["@copyright Copyright (c) {year} jucat"],
    "doxdocgen.file.versionTag": "@version 0.1",
    "doxdocgen.file.fileTemplate": "@file {name}",
    "doxdocgen.file.fileOrder": [
      "file",
      "author",
      "email",
      "brief",
      "version",
      "date",
      "empty",
      "copyright",
      "empty",
      "custom"
    ],

    // 自动生成的函数注释模板,不区分源文件和头文件
    "doxdocgen.generic.order": [
      "brief",
      "tparam",
      "param",
      "return"
    ],

    // 自定义注释模块
    "doxdocgen.file.customTag": [
      "@par 修改日志:",
      "<table>",
      "<tr><th>Date       <th>Version <th>Author  <th>Description",
      "<tr><td>{date} <td>1.0     <td>wangh     <td>内容",
      "</table>",
    ],

    // ---------- doxygen 注释配置 ---------- end line

文档生成

安装 doxygen-gui :

bash 复制代码
sudo apt install doxygen-gui

终端执行命令:

bash 复制代码
doxywizard

doxygen-gui 配置:

运行完成后,在 "文档输出位置" 目录下的 files.html 文件就是代码项目文档。

点击 类 -> 类列表 ,再点击查看类详细说明。

源文件注释:

头文件注释:

文档效果:

更多 doxygen 关键字参考文章开头的"参考",文档效果就自己测试看看了。

相关推荐
Evand J41 分钟前
【MATLAB例程】基于IMM-CKF的AOA+测距融合的二维移动目标跟踪定位
开发语言·matlab·目标跟踪
JianZhen✓2 小时前
IM 聊天列表为什么总“消息乱跳“:有序插入、时间轴派生、本地截断、已读回执
开发语言·前端·php
FungLeo2 小时前
FengCMS · PHP+MySQL 升级实录· 代码审计怎么闭环:REVIEW到 CLOSURE 四件套,12 个域90 篇修复文档跟到底
开发语言·mysql·php·代码审计·fengcms
七夜zippoe2 小时前
多轮对话管理:Session/记忆在 Java 后端怎么存(存储设计实战)
java·开发语言·ai·session·记忆
小小bugbug2 小时前
带工作窃取的线程池
c++·线程池
屿华AI2 小时前
AUTOSAR 实战-诊断工具 | 基于 Python 与 USB-CANFD 的 UDS 诊断测试工具设计与实现
开发语言·python·测试工具
SomeOtherTime3 小时前
番外篇(第 12 讲):走向工业界深水区——从物理定律看 Rust 在真实工程中的“降维打击”与“阿喀琉斯之踵”
开发语言·rust
黑客笔记4 小时前
Python 进程池和线程池:用等待任务理解并发
开发语言·python
pps-key16 小时前
网络攻防入门:从“黑客梦”到合法实操(生存篇)
开发语言·web安全·php
汤姆宝库17 小时前
BPE分词器的完整实现:字节对合并与词表构建
开发语言·人工智能·c#