C++ 注释：单行 // 与多行 /* */

注释的用途

注释是源代码中会被 C++ 编译器完全忽略的文字。它永远不会进入编译后的程序，纯粹是写给读代码的人看的。你可以用注释来解释某件事为什么要这样做、留下提醒，或者在不删除代码的情况下暂时禁用它。

在你已经掌握的 C++ 语法基础上，注释是少数几乎可以放在任何地方、编译器都会直接跳过的东西之一。C++ 有两种注释：单行注释（//）和多行块注释（/* */）。

单行注释

两个斜杠（//）开始一段注释，一直延续到当前行的末尾。编译器会跳过从 // 到换行之间的所有内容。

#include <iostream>
using namespace std;

int main() {
    // Print a greeting to the console
    cout << "Hello, C++!" << endl;

    int score = 90; // a comment can also sit after code
    cout << score << endl;
    return 0;
}

注意第二条注释和真正的代码在同一行。// 之前的部分照常运行，只有它后面的部分被忽略。这是写简短说明最常用的注释风格。

多行块注释

当说明跨越好几行时，块注释比在每一行前面加 // 更整洁。块注释以 /* 开始，以 */ 结束。两者之间的所有内容，不管有多少行，都会被忽略。

#include <iostream>
using namespace std;

int main() {
    /*
     * This program shows a block comment.
     * The leading asterisks on each line are just a
     * convention for readability - they are not required.
     */
    cout << "Block comments are handy." << endl;
    return 0;
}

沿着左侧对齐的 * 字符只是一种风格惯例，并不是规则。真正起作用的只有开头的 /* 和结尾的 */。块注释甚至可以放在一行的中间，int x = 5 /* width */ + 2; 是合法的，不过这样很快就会变得难以阅读。

注释掉代码

注释是在做实验时禁用代码而不删除它的标准方式。单独一行用 //，一次关闭好几行则用块注释。

#include <iostream>
using namespace std;

int main() {
    cout << "This line runs." << endl;

    // cout << "This line is disabled." << endl;

    /*
    cout << "So is this one," << endl;
    cout << "and this one too." << endl;
    */

    cout << "This line runs as well." << endl;
    return 0;
}

运行它，你只会看到两行“runs”被打印出来。被注释掉的 cout 语句对编译器来说是不可见的。

不能嵌套的陷阱

一个常让新手中招的陷阱：块注释不能嵌套。无论前面有多少个 /*，第一个 */ 都会结束注释。所以你不能把一个 /* ... */ 块包在另一个 /* ... */ 块里面：里面的 */ 会结束整个注释，它后面的所有内容又变回了代码（通常会导致语法错误）。

/*  Trying to disable a region that already has a block comment...
    int n = 10; /* the width */
    cout << n;
*/  // the first */ above already closed the comment - this line is now stray code

外层注释在 the width 后面的 */ 处就结束了，所以剩下的部分不再被注释，编译器会卡在末尾多出来的 */ 上。当你需要禁用一段本身已包含块注释的代码时，改为在每一行前面加 //。大多数编辑器用一个快捷键就能对整个选区切换行注释，完全绕开了这个问题。

好注释与噪音

注释应该解释代码本身说不清楚的东西。仅仅复述代码的注释只会添乱，而且随着代码修改，往往会变得过时。

// Bad: just repeats what the code obviously does
i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

努力让代码本身通过清晰的命名和结构变得易读，把注释留给为什么：意图、取舍、边界情况，以及相关背景的链接。如果你发现自己在写注释解释一行令人困惑的代码，这通常是在提示你：应该给变量改个名字，或者把逻辑拆分成一个命名良好的函数。

下一篇：变量

现在你已经会给代码加注释了，下一个基础构件是在代码中存储数据。下一篇讲解变量：如何声明变量，它们可以保存哪些内置类型，以及 C++ 作为静态类型语言所强制执行的规则。