代码注释

代码注释几乎是每个编程语言都必有的功能，它的主要作用就是让开发者能够更好、更快速的阅读代码理解其的意思。在 C++ 中有着多种的注释方式，每种注释方式都有其对应的使用场景。

基础注释

在 C++ 中最基本且最常用的注释方式有以下两种:

• 单行注释

• 多行注释

单行注释

单行注释以两个双斜杠 // 开始直至本行结束，编译器会在编译的过程中自动忽略双斜杠后面的全部内容。

单行注释通常用来描述解释变量的用处，其通常写在需要解释的代码上方一行。具体使用方式如下:

// 小明的年龄为18岁
int age = 18;

由于单行注释的特性，也可以将其写在某行代码的后方，具体使用场景为定义了多个变量需要描述解释。

小技巧

为了让代码看起来更加的整洁美观，我们通常会使用 Tab 键来让代码或注释缩进使其与上下行的代码垂直对齐。

std::cout << "Modern C++ Full-Stack Tutorial" << std::endl;    // 书籍名称
std::cout << "Author: 龙森" << std::endl;                       // 书籍作者

多行注释

多行注释以单斜杠加星号开头 /* 以星号加单斜杠结尾 */ 编译器会忽略这两个多行注释符号内的所有内容，常用于需要大量说明的代码。例如用来描述某个函数的功能和所需的参数。

/*
    整型函数
    进行 A + B 操作
    将返回计算结果
*/

int Addition(int A, int B) {
    int C = A + B;
    return C;
}

注意

C++ 中的多行注释不能嵌套使用，即不能在一个 /* */ 注释内部再使用另一个 /* */ 注释。

如果在开发过程中你需要临时屏蔽某些代码但又不想删除的时候，也可以使用注释来进行屏蔽。

// int C = A + B;

文档注释

在普通注释的基础上，文档注释可以使用特殊工具如 Doxygen 提取 C++ 的代码和对应的注释，编译成一个在线文档，能够让开发者在无需翻阅大量代码的前提下精准地找到自己想要查看的代码的对应描述。同时，高级注释语法支持将整个代码文件进行注释描述。

代码文件注释

/**
 * @file        当前代码文件名
 * @brief       此代码文件的说明
 * @details     一些细节
 * @mainpage    工程概览
 * @author      作者
 * @version     版本号
 * @date        年-月-日
 */

常用 Doxygen 标签

标签	用途	示例
@file	文件名	@file main.cpp
@brief	简要描述	@brief Main function of the program
@details	详细描述	@details This function initializes the system and starts the main loop
@param	参数说明	@param value The input value to process
@return	返回值说明	@return The result of the calculation
@note	注意事项	@note This function must be called before initialization
@warning	警告信息	@warning This function may throw exceptions
@author	作者信息	@author John Doe
@date	日期	@date 2023-01-01

更多高级注释语法可以前往 Doxygen 官网 https://www.doxygen.nl/manual/index.html 查看官方文档

提醒注释

该类型注释通常由开发工具定义与实现具体功能，其中 TODO 已经被绝大多数的开发工具所兼容，它的功能是显示一个待办事项常用于用来标记接下来所要进行的任务或所需修改的功能。

// TODO 增加分流功能

其它类型:

注释类型	作用和使用场景	示例
TODO	待办事项：最常用的一种，用于标记任何需要完成的任务	// TODO: 实现用户身份验证逻辑
FIXME	待修复：明确指出代码中存在一个已知但尚未修复的 bug。	// FIXME: 当输入为负数时，此函数会崩溃
HACK	临时方案：当前代码能正常工作，但未来应该用更好的方法重构。	// HACK: 为了临时解决渲染延迟，这里强制刷新了两次
UNDONE	未完成：表示某段代码或一个功能块的开发被中断，尚未彻底完成。	// UNDONE: 重构到一半，需要继续完成剩余部分
XXX	警示/危险：用于标记代码中存在严重问题或可能导致风险的地方，需要特别注意。	// XXX: 这里的内存管理逻辑可能导致泄露
NOTE	笔记/说明：用于对某段复杂的代码进行解释或提供额外信息，帮助他人理解。	// NOTE: 这里使用位运算是为了提高性能

注意

不同的开发工具对提醒注释的支持程度不同，有些工具仅支持基本的 TODO，而有些工具支持更多类型并提供高级功能（如任务列表、跳转等）。具体支持情况需要在你的开发工具上进行测试。

注释规则

编写代码注释时候通常需要遵守以下几个默认行为规范。

实时更新: 当你对代码进行了改动，请确保注释也进行对应的更新，防止出现注释与代码的实际功能有差异。过时的注释比没有注释更糟糕。

表明实意: 注释应该表达代码无法直接传递的实际意思，而不是重复的表达代码的内容。

注释方案: 在大型项目中尽量使用 Doxygen 注释语法，这样做的好处就是能够提升注释的可读性也可编译成项目文档。

适度注释: 不要为每一行代码都添加注释，这会增加维护负担。只在必要的地方添加注释，解释 “为什么” 而不是 “是什么”。

---