目录

  1. 什么是 C++ 注释？
  2. 单行注释 (//)
  3. 多行注释 (/* */)
  4. 文档注释（Doxygen 格式）
  5. 代码注释的最佳实践
  6. 参考资料

1. 什么是 C++ 注释？

注释（Comments） 是程序中的非执行代码，用于解释代码的功能、逻辑或用途，以提高代码的可读性。C++ 提供了单行注释、多行注释和文档注释三种方式。

2. 单行注释 (//)

单行注释用于对单行代码进行解释，使用 // 开头，后面的内容不会被编译。

示例：

#include <iostream>

int main() {
    // 输出 "Hello, World!"
    std::cout << "Hello, World!" << std::endl;
    return 0;  // 返回 0 表示程序执行成功
}

说明：

  • // 输出 "Hello, World!" 解释了 std::cout 语句的作用。
  • // 返回 0 表示程序执行成功 说明 return 0; 的意义。

3. 多行注释 (/* */)

多行注释用于注释多行代码，在 /* 和 */ 之间的内容都会被忽略。

示例：

#include <iostream>

int main() {
    /* 这个程序用于输出 "Hello, World!"
       使用 std::cout 进行标准输出 */
    std::cout << "Hello, World!" << std::endl;

    /*
       这段代码演示了 C++ 的多行注释
       return 0; 表示程序成功执行
    */
    return 0;
}

注意：

  • /* 开头，*/ 结尾，内部的所有内容都会被忽略。
  • 多行注释可以用于屏蔽代码，例如： /* int a = 10; std::cout << a; // 这段代码不会被执行 */

4. 文档注释（Doxygen 格式）

在大型项目中，使用 Doxygen 进行自动化文档生成是一个最佳实践。Doxygen 提供的文档注释通常用于描述函数、类、变量等。

基本格式

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

示例

#include <iostream>

/**
 * @class Car
 * @brief 代表汽车类
 */
class Car {
public:
    /**
     * @brief 启动汽车
     */
    void start() {
        std::cout << "Car is starting..." << std::endl;
    }
};

int main() {
    Car myCar;
    myCar.start();
    return 0;
}

常见 Doxygen 注释标签

标记作用
@brief简要说明
@param说明函数参数
@return说明返回值
@class说明类

如何生成文档？

  • 安装 Doxygen：Doxygen 官网
  • 运行： doxygen -g # 生成配置文件 doxygen Doxyfile # 生成文档

5. 代码注释的最佳实践

✅ 好的注释习惯

✔ 解释复杂逻辑：

// 计算斐波那契数列（递归实现）
int fibonacci(int n) {
    if (n <= 1) return n; // 递归基准条件
    return fibonacci(n - 1) + fibonacci(n - 2);
}

✔ 标注 TODO 和 FIX

// TODO: 需要优化为动态规划
// FIXME: 可能会出现栈溢出

✔ 为关键代码提供解释

// 使用二分查找法查找目标值
int binarySearch(int arr[], int left, int right, int target) {
    while (left <= right) {
        int mid = left + (right - left) / 2;  // 防止溢出
        if (arr[mid] == target) return mid;
        if (arr[mid] < target) left = mid + 1;
        else right = mid - 1;
    }
    return -1;
}

❌ 避免不良注释习惯

❌ 不要写多余的注释

int a = 10;  // 声明一个整数变量 a，并赋值为 10

❌ 不要使用过时的注释

// 旧代码（已经删除）

❌ 不要过度注释

/* 这段代码用于计算两个整数的和，并返回结果 */
int add(int a, int b) {
    return a + b;
}

6. 参考资料

总结

  1. 单行注释 (//) 适用于短代码行注释
  2. 多行注释 (/* */) 适用于较长注释或屏蔽代码
  3. Doxygen 注释 适用于自动化文档生成
  4. 遵循注释最佳实践，提高代码可读性 🚀