C++ 注释

C++ 中的注释

注释是 C++ 源代码中用来解释说明的文本。它们会被编译器忽略，但对于人类读者（包括未来的你！）理解代码的用途、逻辑或用法至关重要。

C++ 支持两种主要的注释风格：

1. 单行注释 (//)

单行注释以 // 开头，并持续到该物理行的末尾。它常用于简要解释一行代码或一小段代码。

#include <iostream> // 包含标准输入输出库

int main() { // 程序入口点
    // 向控制台打印问候消息
    std::cout << "Hello, World!" << std::endl; // std::endl 也会刷新输出缓冲区

    return 0; // 表示成功执行
}

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

多行注释以 /* 开头，以 */ 结尾。这对分隔符之间的所有内容，即使跨越多行，都被视为注释。

/*
 * 这是一个多行注释。
 * 它可以跨越多行，常用于
 * 函数描述、文件头信息，或临时
 * 禁用代码块。
 */
#include <iostream>

int main() {
    /* std::cout << "This line is commented out." << std::endl; */ // 这行代码被注释掉了。
    std::cout << "This line is active." << std::endl;
    return 0;
}

注释的嵌套

通常，你可以在 /* ... */ 块内嵌套 // 注释，并且 /* 和 */ 分隔符在 // 注释中没有特殊含义。

/*
  这个块演示了嵌套。
  // 这个单行注释在多行注释里面。
  int x = 5; // 这里仍然可以使用 // 。
*/

// 这行 /* 在这里 */ 没有 /* 任何 */ 特殊含义。

但是，你不能直接嵌套 /* ... */ 注释。遇到的第一个 */ 将会关闭注释块。

/* 这是外部注释。
   /* 这个内部注释尝试 */ 会导致问题！
   上面的第一个 */ 提前关闭了外部注释。
   这里的文本将被编译器视为代码，可能导致错误。
*/

注释的最佳实践

• 注释 原因，而非 内容： 好的代码通常能清楚地表达 内容。注释应该解释原因、意图或非显而易见的方面。
• 保持注释更新： 过时的注释比没有注释更糟糕。如果你修改了代码，请更新相应的注释。
• 使用注释进行文档说明： 解释函数的作用、参数和返回值，以及类的作用。
• 避免过度或显而易见的注释： 对 i++; // Increment i 这样的代码加注释只会增加冗余，无助于提高清晰度。
• 使用 TODO 或 FIXME 标签： 标记需要未来工作或修复的区域（例如，// TODO: Implement error handling）。许多 IDE 都能识别这些标签。

注释是编写可维护且易于理解的 C++ 代码的重要组成部分。