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

原文链接：1.2 — Comments

声明：

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

---

1.2 — 注释

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

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

---

单行注释

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

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

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

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
1
2
3

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

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?
1
2
3

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

// 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";
1
2
3
4
5
6
7
8

作者注

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

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

#include <iostream>

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

    return 0;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

---

多行注释

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

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

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

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

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

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

1
2
3

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

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

警告

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

---

正确使用注释

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

// 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.
1
2
3

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

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

/* 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. */
1
2
3

// 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
1
2
3
4
5
6

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

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

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

不好的注释：

// Set sight range to 0
sight = 0;
1
2

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

不好的注释：

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

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

好注释：

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

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

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

好注释：

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

最后，注释应该以对不知道代码做什么的人有意义的方式编写。通常情况下，程序员会说“这很明显！我不可能忘记这件事”。你猜怎么着？这并不明显，你会惊讶于你忘记的速度有多快。