【Learncpp中文翻译版】【1.2 — 注释】

原文链接：1.2 — Comments

声明：

• 本文旨在方便了解学习C++语法，切勿用于任何商业用途。
• 由于本人英语水平有限，文章中可能存在语义错误，如有疑问请参照原文，也可以在评论区指出错误。

---

1.2 — 注释

注释是直接插入到程序源代码中的程序员可读注释。编译器会忽略注释，仅供程序员使用。

在 C++ 中有两种不同风格的注释，它们都有相同的目的：帮助程序员以某种方式记录代码。

---

单行注释

该//符号开始一个 C++ 单行注释，它告诉编译器忽略从//符号到行尾的所有内容。例如：

std::cout << "Hello world!"; // Everything from here to the end of the line is ignored

通常，单行注释用于对单行代码进行快速注释。

std::cout << "Hello world!\n"; // std::cout lives in the iostream library
std::cout << "It is very nice to meet you!\n"; // these comments make the code hard to read
std::cout << "Yeah!\n"; // especially when lines are different lengths

将注释放在行的右侧会使代码和注释都难以阅读，尤其是在行很长的情况下。如果行很短，注释可以简单地对齐（通常到制表位），如下所示：

std::cout << "Hello world!\n";                 // std::cout lives in the iostream library
std::cout << "It is very nice to meet you!\n"; // this is much easier to read
std::cout << "Yeah!\n";                        // don't you think so?

但是，如果行很长，将注释放在右侧会使您的行变得很长。在这种情况下，单行注释通常放在它正在注释的行之上：

// std::cout lives in the iostream library
std::cout << "Hello world!\n";

// this is much easier to read
std::cout << "It is very nice to meet you!\n";

// don't you think so?
std::cout << "Yeah!\n";

作者注

上面的陈述代表了我们第一次遇到代码片段。因为片段不是完整的程序，它们不能自己编译。相反，它们的存在是为了以简洁的方式展示特定的概念。

如果你想编译一个片段，你需要把它变成一个完整的程序才能编译。通常，该程序将如下所示：

#include <iostream>

int main()
{
    // Replace this line with the snippet of code you'd like to compile

    return 0;
}

---

多行注释

和符号对表示 C 风格的多行注释/*。*/符号之间的所有内容都将被忽略。

/* This is a multi-line comment.
   This line will be ignored.
   So will this one. */

由于符号之间的所有内容都被忽略了，你有时会看到程序员“美化”他们的多行注释：

/* This is a multi-line comment.
 * the matching asterisks to the left
 * can make this easier to read
 */

多行样式注释不能嵌套。因此，以下将产生意想不到的结果：

/* This is a multi-line /* comment */ this is not inside the comment */
// The above comment ends at the first */, not the second */

当编译器试图编译它时，它将忽略从第一个/*到第一个 */ 的所有内容。由于“ this is not inside the comment */ ”不被认为是注释的一部分，编译器将尝试编译它。这将不可避免地导致编译错误。

这是使用语法荧光笔非常有用的一个地方，因为注释的不同颜色应该清楚地说明什么被认为是注释的一部分，而不是。

警告

不要在其他多行注释中使用多行注释。在多行注释中包含单行注释是可以的。

---

正确使用注释

通常，注释应该用于三件事。首先，对于给定的库、程序或函数，最好使用注释来描述库、程序或函数的功能。这些通常放置在文件或库的顶部，或紧接在函数之前。例如：

// This program calculates the student's final grade based on their test and homework scores.
// This function uses Newton's method to approximate the root of a given equation.
// The following lines generate a random item based on rarity, level, and a weight factor.

所有这些注释使读者无需查看实际代码即可很好地了解库、程序或函数试图完成的工作。用户（可能是其他人，或者如果您想重用以前编写的代码，则您）可以一眼看出代码是否与他或她想要完成的任务相关。当作为团队的一员工作时，这一点尤其重要，因为不是每个人都熟悉所有代码。

其次，在上述库、程序或函数中，注释可用于描述代码将如何实现其目标。

/* To calculate the final grade, we sum all the weighted midterm and homework scores
    and then divide by the number of scores to assign a percentage, which is
    used to calculate a letter grade. */

// To generate a random item, we're going to do the following:
// 1) Put all of the items of the desired rarity on a list
// 2) Calculate a probability for each item based on level and weight factor
// 3) Choose a random number
// 4) Figure out which item that random number corresponds to
// 5) Return the appropriate item

这些注释让用户了解代码将如何实现其目标，而无需了解每一行代码的作用。

第三，在语句级别，应该使用注释来描述代码为什么做某事。错误的语句注释解释了代码在做什么。如果您曾经编写过如此复杂的代码，需要注释来解释语句在做什么，那么您可能需要重写您的语句，而不是注释它。

下面是一些不好的行注释和好的语句注释的例子。

不好的注释：

// Set sight range to 0
sight = 0;

原因：我们已经可以通过查看语句看到视线被设置为 0

不好的注释：

// Calculate the cost of the items
cost = quantity * 2 * storePrice;

原因：我们可以看到这是一个成本计算，但是为什么数量要乘以2呢？

好注释：

// We need to multiply quantity by 2 here because they are bought in pairs
cost = quantity * 2 * storePrice;

原因：现在我们知道为什么这个公式有意义了。

程序员经常不得不在以一种方式解决问题或以另一种方式解决问题之间做出艰难的决定。评论是提醒自己（或告诉其他人）您做出一个决定而不是另一个决定的原因的好方法。

好注释：

// We decided to use a linked list instead of an array because
// arrays do insertion too slowly.

最后，注释应该以对不知道代码做什么的人有意义的方式编写。通常情况下，程序员会说“这很明显！我不可能忘记这件事”。你猜怎么着？这并不明显，你会惊讶于你忘记的速度有多快。😃 您（或其他人）稍后会感谢您用人类语言写下您的代码的内容、方式和原因。阅读单独的代码行很容易。不了解他们要完成的目标是什么。

作者注

在本教程系列的其余部分中，我们将在代码块中使用注释来引起您对特定事物的注意，或者帮助说明事物是如何工作的（同时确保程序仍然可以编译）。精明的读者会注意到，按照上述标准，这些z注释中的大多数都是可怕的。
:) 当您阅读其余教程时，请记住，这些注释是为了教育目的，而不是试图展示好的注释是什么样的。

---

注释掉代码

将一行或多行代码转换为注释称为注释掉您的代码。这提供了一种方便的方法来（暂时）将部分代码排除在已编译的程序中。

要注释掉一行代码，只需使用 // 样式的注释将一行代码暂时变成注释即可：
未注释掉：

std::cout << 1;

注释掉：

//    std::cout << 1;

要注释掉代码块，请在多行代码上使用 // 或 /* */ 样式注释将代码块暂时变成注释。

未注释掉：

std::cout << 1;
std::cout << 2;
std::cout << 3;

注释掉：

//    std::cout << 1;
//    std::cout << 2;
//    std::cout << 3;

或者

/*
    std::cout << 1;
    std::cout << 2;
    std::cout << 3;
*/

您可能想要这样做的原因有很多：

1. 您正在编写一段尚未编译的新代码，您需要运行该程序。如果存在编译器错误，编译器将不允许您编译代码。注释掉无法编译的代码将允许程序编译，以便您可以运行它。准备好后，您可以取消注释代码，然后继续处理它。
2. 您编写了可以编译但无法正常工作的新代码，直到稍后您才有时间修复它。注释掉损坏的代码将确保损坏的代码不会执行并导致问题，直到您可以修复它。
3. 找出错误的根源。如果程序没有产生预期的结果（或崩溃），有时禁用部分代码以查看是否可以隔离导致其无法正常工作的原因可能很有用。如果您注释掉一行或多行代码，并且您的程序开始按预期运行（或停止崩溃），那么您最后注释掉的内容很可能是问题的一部分。然后，您可以调查这些代码行导致问题的原因。
4. 您想用另一段代码替换一段代码。除了删除原始代码之外，您还可以将其注释掉并留在那里以供参考，直到您确定新代码正常工作。一旦你确定你的新代码可以工作，你可以删除旧的注释掉的代码。如果您的新代码无法正常工作，您可以随时删除新代码并取消注释旧代码以恢复到之前的状态。

在开发过程中注释掉代码是一件很常见的事情，因此许多 IDE 都支持注释掉突出显示的代码部分。您访问此功能的方式因 IDE 而异。

Tip:

如果您总是对普通注释使用单行注释，那么您始终可以使用多行注释来注释您的代码而不会发生冲突。如果您使用多行注释来记录您的代码，那么使用注释注释掉代码会变得更具挑战性。

如果您确实需要注释掉包含多行注释的代码块，您还可以考虑使用#if 0预处理器指令，我们将在第 2.10 课 - 预处理器简介中讨论该指令。

---

概括

• 在库、程序或函数级别，使用注释来描述.
• 在库、程序或函数内部，使用注释来描述如何.
• 在语句级别，使用注释来描述原因。