注释是程序员可读的注释,直接插入到程序的源代码中。注释会被编译器忽略,仅供程序员使用。在 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";
多行注释
和一对符号表示 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.
所有这些注释都可以让读者很好地了解库、程序或函数试图完成的任务,而无需查看实际代码。
其次,在上述库、程序或函数中,注释可用于描述代码将如何实现其目标。
/* 为了计算最终成绩,我们将所有加权的期中考试和作业成绩相加,
然后除以成绩数量以得出一个百分比,该百分比用于计算字母等级。 */
// 为了生成一个随机物品,我们将执行以下步骤:
// 1) 将所需稀有度的所有物品放在一个列表上
// 2) 根据级别和权重因子计算每个物品的概率
// 3) 选择一个随机数
// 4) 确定该随机数对应的物品是哪一个
// 5) 返回相应的物品
这些注释让用户了解代码将如何实现其目标,而无需了解每一行代码的作用。
第三,在语句级别,应该使用注释来描述代码为什么要做某事。错误的语句注释解释了代码的作用。如果您编写的代码非常复杂,需要注释来解释语句的作用,那么您可能需要重写语句,而不是对其进行注释。
以下是一些不好的行注释和好的语句注释的示例。
不好的注释:
// 将sight设置为0
sight = 0;
原因:通过查看语句我们已经可以看到sight被设置为0
// 计算物品的成本
cost = quantity * 2 * storePrice;
原因:我们可以看到这是一个成本计算,但是为什么数量要乘以2呢?
好的注释:
// 这里我们需要将数量乘以2,因为它们是成对购买的
cost = quantity * 2 * storePrice;
原因:现在我们知道为什么这个公式有意义了。
注释掉代码
将一行或多行代码转换为注释称为注释掉代码。这提供了一种方便的方法(暂时)排除部分代码包含在编译的程序中。
要注释掉单行代码,只需使用 // 样式注释将一行代码暂时变成注释即可:
未注释掉:
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;
*/
您可能想要这样做的原因有很多:
- 您正在编写一段尚未编译的新代码,并且需要运行该程序。如果存在编译器错误,编译器将不会让您编译代码。注释掉无法编译的代码将使程序能够编译,以便您可以运行它。准备好后,您可以取消注释代码并继续处理它。
- 您编写了可以编译但无法正常工作的新代码,并且您直到稍后才有时间修复它。注释掉损坏的代码将确保损坏的代码不会执行并导致问题,直到您可以修复它。
- 找出错误的根源。如果程序没有产生所需的结果(或崩溃),有时禁用部分代码以查看是否可以隔离导致其无法正常工作的原因会很有用。如果您注释掉一行或多行代码,并且您的程序开始按预期工作(或停止崩溃),那么您最后注释掉的内容很可能是问题的一部分。然后您可以调查这些代码行导致问题的原因。
- 您想用另一段代码替换一段代码。您不仅可以删除原始代码,还可以将其注释掉并将其留在那里以供参考,直到您确定新代码可以正常工作为止。一旦确定新代码可以正常工作,您就可以删除旧的注释掉的代码。如果您无法使新代码正常工作,您可以随时删除新代码并取消注释旧代码以恢复到之前的状态。
注释掉代码是开发过程中常见的事情,因此许多 IDE 都支持注释掉突出显示的代码部分。访问此功能的方式因 IDE 而异。
对于 Visual Studio 用户
您可以通过编辑菜单 > 高级 > 注释选择(或取消注释选择)来注释或取消注释选择。
对于 Code::Blocks 用户
您可以通过“编辑”菜单 >“注释”(或“取消注释”、“切换注释”或任何其他注释工具)对所选内容进行注释或取消注释。
对于 VS Code用户
您可以通过按 ctrl-k-c 注释掉所选内容,并通过按 ctrl-k-u 取消注释所选内容。
概括
- 在库、程序或函数级别,使用注释来描述内容。
- 在库、程序或函数内部,使用注释来描述如何。
- 在语句级别,使用注释来描述原因。
原创文章,作者:jkhxw,如若转载,请注明出处:https://www.jkhxw.com/cpp-comments/