1-2 注释
注释comment是直接插入程序源代码中的可供程序员阅读的注记。编译器会忽略注释，它们仅供程序员使用。
在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";
作者注:
在本教程系列中，我们的示例分为以下几类：
- 完整程序（包含 main() 函数的程序）。这类程序可直接编译运行。
- 代码片段（如上文所示的语句）。我们用这些片段以简洁的方式演示特定概念。
我们不建议您编译代码片段。但若您仍需编译，则需将其扩展为完整程序。通常该程序结构如下所示：#include <iostream> int main() { // Replace this line with the snippet(s) 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 */
当编译器尝试编译此代码时，它会忽略从第一个 /* 到第一个 */ 之间的所有内容。由于此处不在注释范围内，因此 */ 不被视为注释的一部分，编译器将尝试编译它。这必然导致编译错误。
此时语法高亮工具便大显身手——通过不同颜色标注，可清晰区分注释内容与非注释内容。
警告
请勿在多行注释内部嵌套多行注释。将单行注释包裹在多行注释中则无妨。
正确使用注释
通常，注释应用于三种情况。首先，对于特定的库、程序或函数，注释最适合用于描述该库、程序或函数的功能First, for a given library, program, or function, comments are best used to describe what the library, program, or function, does.。这类注释通常置于文件或库的顶部，或紧接在函数之前。例如：
// 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.
所有这些注释都能让读者在无需查看实际代码的情况下，清晰了解库、程序或函数的实现目标。用户（可能是他人，也可能是试图复用自己先前代码的你）能一目了然判断代码是否符合其需求。这在团队协作中尤为重要——毕竟并非所有人都熟悉全部代码。
其次，在上述库、程序或函数内部，注释可用于阐述代码实现目标的具体方式Second, within a library, program, or function described above, comments can be used to describe how the code is going to accomplish its goal.。
/* 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
这些注释让用户无需理解每行代码的具体功能，就能大致了解代码如何实现其目标。
第三，在语句层面，注释应用于说明代码执行操作的原因Third, at the statement level, comments should be used to describe why the code is doing something.。糟糕的语句注释会解释代码正在做什么。若你编写的代码复杂到需要注释来解释语句功能，那么你可能需要重写该语句，而非添加注释。
以下是糟糕的行注释与优质语句注释的对比示例：
糟糕的注释：
// Set sight range to 0
sight = 0;
原因：通过查看该语句，我们已经可以看出视图被设置为0
良好注释：
// The player just drank a potion of blindness and can not see anything
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.
// We're going to use Newton's method to find the root of a number because
// there is no deterministic way to solve these equations.
最后，注释的撰写方式应让完全不懂代码功能的人也能理解。程序员常会说：“这段代码的功能很明显！我绝对不会忘记它。”猜猜怎么着？它并不明显，而你会惊讶于自己遗忘的速度有多快。😃 当你（或他人）日后需要理解代码时，会庆幸自己用人类语言记录了代码的“做什么”、“如何做”和“为何做”。阅读单行代码很简单，理解其背后的目标却非易事。
相关内容:
我们在第1.7课——关键字与命名标识符中讨论了变量声明语句的注释。
最佳实践:
请在代码中大量添加注释，且要像向完全不懂代码功能的人解释那样撰写注释。切勿假设自己会记得当初做出特定选择的原因。
作者注:
在本教程系列的后续内容中，我们将使用代码块内的注释来引导您关注特定细节，或帮助阐释工作原理（同时确保程序仍可编译）。敏锐的读者会发现，按上述标准衡量，这些注释大多堪称灾难。😃 阅读后续教程时请谨记：这些注释旨在实现特定教学目的，而非展示优质注释的范例。
顺带一提……:
诸如Doxygen之类的文档生成程序旨在通过多种方式协助生成和利用文档。它们的主要功能包括：
- 帮助规范代码注释方式。
- 生成图表、可视化内容及交叉链接，便于理解代码结构。
- 将文档导出为其他格式（如HTML），便于与他人共享（例如团队成员或需要集成你所编写代码的开发者）。
学习语言时你可能用不到这些工具，但未来（尤其在专业环境中）可能会接触到它们或发现它们的实用价值。
注释代码
将一行或多行代码转换为注释称为注释commenting out代码。这提供了一种便捷的方式，可将代码的某些部分（暂时）排除在编译程序之外。
要注释单行代码，只需使用 // 风格的注释符将该行代码临时转换为注释：
未注释Uncommented out：
std::cout << 1;
注释Commented out：
// 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;
*/
你可能需要这样做有以下几个原因：
- 当你在编写一段尚未能编译通过的新代码时，却需要运行程序。编译器在存在编译错误时会阻止代码编译。将无法编译的代码注释掉，就能让程序顺利编译并运行。待准备就绪后，再取消注释继续完善代码即可。
- 编写的新代码虽能编译却运行异常，而你暂时无暇修复。将故障代码注释掉可确保其不会执行并引发问题，直至你完成修复。
- 定位错误根源。当程序未产生预期结果（或发生崩溃）时，禁用部分代码有助于定位故障根源。若注释掉一行或多行代码后程序恢复正常运行（或停止崩溃），则最近注释掉的代码很可能就是问题所在。此时可深入调查这些代码引发故障的原因。
- 需要用新代码替换旧代码时。与其直接删除原有代码，不如将其注释保留作为参考，直至确认新代码运行正常。待新代码验证无误后，再移除被注释的旧代码。若新代码无法正常工作，可随时删除新代码并取消旧代码注释，恢复至原有状态。
注释代码是开发过程中常见操作，因此多数集成开发环境（IDE）都支持对选定代码段进行批量注释。具体操作方式因IDE而异。
对于 Visual Studio 用户：
您可通过“编辑”菜单 > “高级” > “注释选定内容”（或“取消注释选定内容”）对选定内容进行注释或取消注释。
对于 Code::Blocks 用户
可通过编辑菜单 > 注释（或取消注释、切换注释状态，或其他注释工具）对选定内容进行注释或取消注释。
对于 VS Code 用户
按下 ctrl-/. 即可对选定内容进行注释或取消注释。
提示:
若您始终使用单行注释进行常规注释，则可随时使用多行注释来注释代码而不会产生冲突。但若您使用多行注释来记录代码，则通过注释来注释代码会变得更具挑战性。若需注释掉包含多行注释的代码块，也可考虑使用#if 0预处理指令，该指令将在第2.10节——预处理器入门中详细讲解。
摘要
- 在库、程序或函数层面，使用注释描述“是什么”。
- 在库、程序或函数内部，使用注释描述“如何实现”。
- 在语句层面，使用注释描述“为何如此”。
浙公网安备 33010602011771号