C++ 注释（Comments）

1. 概述

注释用于解释程序逻辑、记录设计思路、说明接口功能或在调试时暂时屏蔽代码。 C++ 编译器在编译阶段会忽略注释内容，它们不会出现在目标文件中。良好的注释能显著提升代码的可读性与可维护性。

2. 注释的基本类型

C++ 提供两种常见的注释形式：

2.1 单行注释（Single-line Comment）

以 // 开头，直到行尾结束。

// 输出欢迎信息
std::cout << "Hello, World!" << std::endl;

// 在行末添加说明
int count = 10;  // 循环次数

适用于简短说明或临时调试。

2.2 多行注释（Multi-line Comment）

以 /* 开始，以 */ 结束，可以跨越多行。

/*
此部分用于初始化程序资源。
包括：
1. 配置加载
2. 内存分配
3. 日志系统启动
*/
initialize_system();

注意：多行注释 不支持嵌套，即不能在 /* ... */ 内再次使用 /* ... */。

3. 注释编写原则

准确：注释必须与代码逻辑一致。
必要：解释“为什么这样做”，而非“代码做了什么”。
简洁：避免冗长或与代码重复的描述。
及时：修改代码时应同步更新注释。
一致：保持统一的注释风格与格式。

示例：

// 不推荐：重复代码逻辑
int x = x + 1; // x 加 1

// 推荐：说明设计目的
// 自增以保持计数连续性
x++;

4. 文档化注释（Documentation Comments）

在较大的工程中，可以通过特殊格式的注释自动生成接口文档。常用工具为 Doxygen，支持从源码中提取函数、类、参数等说明信息。

4.1 格式示例

/**
 * @brief 计算两个整数的和
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 两数之和
 */
int add(int a, int b) {
    return a + b;
}

或者：

/// 计算矩形面积
/// @param width 宽度
/// @param height 高度
/// @return 面积
double area(double width, double height);

4.2 常用标签

标签	含义	示例
`@brief`	简要说明	`@brief 初始化系统资源`
`@param`	参数说明	`@param path 配置文件路径`
`@return`	返回值说明	`@return 初始化是否成功`
`@note`	备注说明	`@note 必须在主线程调用`
`@warning`	警告信息	`@warning 该函数非线程安全`
`@todo`	待办事项	`@todo 增加异常处理`

5. 实际使用规范

在团队开发或课程项目中，建议采用以下注释习惯：

文件头部：说明文件用途、作者、日期。
函数前：使用文档注释描述功能、参数与返回值。
代码内部：仅在逻辑复杂处添加必要注释。
调试阶段：临时屏蔽代码时使用 //，不保留旧逻辑。

示例：

/**
 * @file user_manager.cpp
 * @brief 用户管理模块
 * @author Ding
 * @date 2025-10-13
 */

/// 初始化用户系统
/// @return 初始化是否成功
bool init_user_system() {
    // TODO: 支持从配置文件加载默认用户
    return true;
}

6. 调试与维护中的注释

调试时临时屏蔽代码

// 禁用日志输出
// std::cout << "Debug info" << std::endl;

避免保留废弃代码

// 不推荐：应使用版本控制系统管理
// old_function();

Keyboard shortcuts

Note of C++