C++ 注释

在编写 C++ 程序时，为关键代码添加注释是非常有必要的。注释是专门写给程序员看的说明文字，编译器在编译代码时会直接忽略所有注释内容，不会把它们编译进最终的可执行程序里。

养成写注释的习惯有很多好处，不仅能帮我们自己理清思路、方便过段时间回头修改，也能让团队里的其他成员更快读懂代码。在 C++ 中，注释主要分为 2 种：一种是 “单行注释”，另一种是 “多行注释”。

C++ 单行注释

在 C++ 中，当注释的内容比较简短、只有一行时，我们可以使用两个连续的斜杠 // 来编写单行注释。从 // 开始一直到当前这一行结束，编译器都会把后面的内容当成注释直接忽略。

语法：

// 单行注释内容

说明：

单行注释既可以单独占一行写在对应代码的正上方，也可以跟在一条简短的代码行尾。书写单行注释时，比较好的规范是在 // 与后面的文字之间留一个空格，这样代码阅读起来会更加清爽直观。

示例 1：使用单行注释

#include <iostream>

int main() {
    // 定义两个整型变量并求和
    int a = 10;         // 定义第 1 个整数
    int b = 20;         // 定义第 2 个整数
    int sum = a + b;    // 计算两数之和

    std::cout << sum;
    return 0;
}

运行结果如下。

30

分析：

当编译器编译上面这段代码时，会自动跳过每一行中 // 后面的所有文字，到了下一行又会恢复正常解析代码。因此，注释不会对程序的运行结果产生任何影响，也不会在屏幕上打印出来。

在实际开发中，如果某条注释用来说明一段代码的整体作用，建议单独占一行放在对应代码的上方。如果只是针对单个变量或简短语句的补充说明，写在代码行尾就可以了，不要在代码行尾拖一条很长的句子。

另外要注意，如果 // 出现在双引号括起来的字符串内部，比如使用 std::cout 打印网址字符串 "https://www.lvyenet.com" 时，里面的 // 只会被当成普通文字输出，而不会识别为注释。

C++ 多行注释

在 C++ 中，当需要说明的内容比较多、一行写不下时，我们可以使用多行注释（也叫 “块注释”）。

语法：

/*
多行注释内容
多行注释内容
*/

说明：

C++ 的多行注释以 /* 开头，并以 */ 结尾，中间可以包含任意多行文字。编译器遇到 /* 时开始忽略后面的内容，直到遇到第一个配对的 */ 才结束注释。

示例 2：使用多行注释

#include <iostream>

/*
计算矩形的面积：
已知矩形的长和宽，
将两者相乘后输出最终面积
*/
int main() {
    int width = 8;
    int height = 5;
    int area = width * height;
    std::cout << area;
    return 0;
}

运行结果如下。

40

分析：

/* 和 */ 之间的多行说明文字组成了一段完整的多行注释，同样不会参与程序执行。当然了，如果说明文字只有两三行，连续使用多行 // 也是完全等价的：

// 计算矩形的面积：
// 已知矩形的长和宽，
// 将两者相乘后输出最终面积

在使用多行注释时，有一条重要的语法限制：多行注释 /* ... */ 是不允许嵌套的。也就是说，不能在一个 /* ... */ 内部再包含另一个 /* ... */，下面我们来看一个例子。

示例 3：多行注释不能嵌套

#include <iostream>

int main() {
    /*
    int a = 10;    /* 初始值 */
    int b = 20;
    */
    int price = 50;
    std::cout << price;
    return 0;
}

运行结果如下。

（报错）error: expected primary-expression before '/' token

分析：

为什么多行注释不能嵌套呢？因为编译器看到最外层的 /* 之后，只要往后遇到第一个 */，也就是 /* 初始值 */ 末尾的那个 */，就会认为整个多行注释已经结束了。

这样一来，原本属于外层注释结尾的那个 */ 就会暴露在注释范围之外。编译器看到斜杠 / 前面缺少合法的表达式，就会直接报语法错误。

临时屏蔽代码与注释习惯

除了用来写说明文字外，注释在日常调试和项目维护中还有不少实用讲究，下面我们来看看最常见的两个方面。

1. 临时屏蔽代码

在调试程序时，我们经常利用注释来临时屏蔽某行代码。比如想测试去掉某行代码后的运行效果，但又不想直接把它删掉，此时就可以先将这行代码注释掉，测试完随时还能恢复回来。

示例 4：临时屏蔽某行代码

#include <iostream>

int main() {
    int stock = 100;
    // stock = 20;
    std::cout << stock;
    return 0;
}

运行结果如下。

100

分析：

由于 stock = 20; 前面加上了 //，这行赋值语句就变成了注释，编译器会直接跳过它，因此最终输出的依然是初始值 100。

在 VSCode 等主流编辑器中，我们可以通过快捷键快速注释或取消注释：先选中一行或多行代码，按下快捷键（Ctrl + /）就能一键给选中的代码全部加上 //，再次按下又能一键取消注释。

不过这里也要提醒小伙伴们：临时注释代码只是调试期间的做法。等代码调试完毕、确认某段旧代码确实不再需要之后，应该直接把它删干净，不要在项目里长期保留大量废弃的代码。

2. 编写注释的注意事项

在实际开发中，并不是注释写得越多就越好。如果每一行简单代码后面都塞一句重复的注释，反而会让代码变得杂乱。编写注释时，建议大家注意以下 3 点：

• 解释 “为什么”，而不是重复字面意思：代码本身一眼就能看懂的操作，不需要再用中文复述一遍。有价值的注释应该用来说明背后的业务原因或特殊限制。
• 清晰的命名胜过补充注释：如果变量名只写一个模糊的 x，还得靠旁边的注释才能看懂含义，不如直接起一个见名知意的名字。关于如何规范起名，我们在上一节 “C++ 标识符” 中已经介绍过了。
• 修改代码时同步更新注释：过期的错误注释很容易误导人。如果我们修改了代码中的数值或逻辑，记得及时更新旁边的注释，避免出现代码和注释不一致的情况。

比如下面这两种写法中，与其给模糊的变量名 x 补一堆字面注释，不如直接起好名字，并把注释留给真正需要交代的业务规则：

// 不推荐
int x = 3;    // 最大尝试次数
x = x + 1;    // 给 x 加 1

// 推荐
// 密码最多允许连续输错 3 次
const int maxAttempts = 3;