C++ 注释

注释是写在代码中的说明文字，编译器会完全忽略它们。虽然注释不影响程序运行，但好的注释能让代码更容易理解、维护和协作。

为什么需要注释

当你写下一行代码时，它的意图在脑海中非常清晰。但几周、几个月后，或者当别人阅读这段代码时，可能就不那么明显了。注释的作用包括：

解释某段代码为什么要这样写。
说明函数的功能、参数和返回值。
临时屏蔽某段代码，方便调试。
记录版本、作者、修改日期等元信息。

注释不是越多越好。过度注释会让代码显得臃肿，而关键的地方没有注释又会让人困惑。最好的注释是解释“为什么”，而不是“做了什么”。

单行注释

单行注释以两个斜杠 // 开头，从 // 开始到该行末尾的所有内容都是注释。

#include <iostream>
using namespace std;

int main()
{
    int score = 95;          // 学生的考试分数
    cout << score << endl;   // 输出分数
    return 0;
}

单行注释通常用于：

简短解释某一行代码的含义。
标注 TODO 或 FIXME。
在代码行尾补充说明。

int result = a + b; // TODO: 这里需要考虑溢出情况

多行注释

多行注释以 /* 开头，以 */ 结尾，中间可以包含任意多行内容。

#include <iostream>
using namespace std;

int main()
{
    /*
       这是一个多行注释。
       它可以跨越多行，适合写较长的说明。
    */
    cout << "Hello Koyuki!" << endl;
    return 0;
}

多行注释通常用于：

在函数或文件开头写详细说明。
临时屏蔽一段代码。
记录版权声明或许可证信息。

/*
 * 文件名：main.cpp
 * 作者：Koyuki
 * 日期：2026-07-16
 * 描述：输出欢迎信息
 */

注释不能嵌套

C++ 的多行注释不能嵌套。也就是说，下面这段代码是错误的：

/*
    外层注释开始
    /* 内层注释 */
    外层注释结束
*/

编译器会把第一个 /* 和第一个 */ 之间的内容当作注释，后面的内容就会导致编译错误。如果需要注释掉包含多行注释的代码，可以使用单行注释逐行注释：

// /*
//     这整段代码都被临时屏蔽
//     /* 内层多行注释 */
// */

用注释调试代码

在调试程序时，经常需要临时禁用某些代码，观察程序行为。用注释来“关掉”代码非常方便：

#include <iostream>
using namespace std;

int main()
{
    int a = 10;
    int b = 20;

    // 临时禁用下面这行
    // int c = a + b;

    cout << "a = " << a << endl;
    cout << "b = " << b << endl;

    return 0;
}

注释的风格建议

1. 注释要简洁清晰

不要写显而易见的注释：

int a = 10; // 把 10 赋值给 a

更好的做法是给变量一个有意义的名字，减少不必要的注释：

int studentCount = 10;

2. 保持注释与代码一致

代码修改后，别忘了同步更新注释。过时的注释比没有注释更危险，因为它会误导阅读者。

3. 在复杂逻辑前加说明

当一段算法或逻辑比较复杂时，可以在前面用多行注释说明思路：

/*
 * 思路：
 * 1. 先读取用户输入的两个整数。
 * 2. 比较它们的大小。
 * 3. 输出较大的那个。
 */
int max(int a, int b)
{
    if (a > b)
    {
        return a;
    }
    return b;
}

4. 文件头注释

在源文件开头写一段文件说明，是团队协作中常见的做法：

/*
 * 项目：Koyuki Palace
 * 文件：main.cpp
 * 描述：程序的入口文件
 */

完整示例

#include <iostream>
using namespace std;

/*
 * 函数：add
 * 功能：计算两个整数的和
 * 参数：a 和 b 是要相加的两个整数
 * 返回值：两数之和
 */
int add(int a, int b)
{
    return a + b;
}

int main()
{
    int x = 10;
    int y = 20;

    // 调用 add 函数计算结果
    int result = add(x, y);

    cout << "x + y = " << result << endl;

    return 0;
}

运行结果：

x + y = 30