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

参考

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

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