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

news2024/10/6 7:01:55

参考

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

C++ doxygen 风格注释示例

ubuntu20 中 doxygen 文档生成

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

注释说明

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

C 风格注释

// 单行注释

/*
多行注释
*/

C ++ 风格注释：

/// 单行注释
//! 单行注释

/**
多行注释
*/
/*!
多行注释
*/

文件注释：时间 + 版权 + 维护作者 + 文件内容
类注释：类的功能 + 用法 + 注意事项
函数注释：

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

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

  不要重复函数声明和定义的注释，没有意义！
变量注释：

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

全局变量：每个全局变量都要说明定义和用途。
实现注释：对巧妙, 晦涩, 重要的地方加以注释。解释代码段功能或为什么这么处理。
TODO注释：对临时方案，不好的代码注释方便日后改进。
弃用注释：在弃用代码上方加// deprecate：弃用说明。弃用代码最好用 // 屏蔽，方便搜索栏发现代码已弃用。

Utuntu20 Vscode Doxygen 自动生成文档

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

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

在 vscode 按 ctrl+shift+p，搜索 “settings”，选择首选项配置（JSON）配置 doxygen 参数。

粘贴下面配置：

    // ---------- 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