注释:代码中的笔记

注释概述

注释是直接插入到程序源代码中的、供程序员阅读的笔记。编译器会忽略注释,它们仅供程序员使用。 在C++中有两种不同风格的注释,它们都服务于相同的目的:以某种方式帮助程序员记录代码。

单行注释

//符号开始了C++的单行注释,它告诉编译器忽略从//符号到行尾的所有内容。例如:

std::cout << "Hello world!"; // 从这里到行尾的所有内容都将被忽略

单行注释的使用方式

通常,单行注释用于对单行代码快速发表评论。

std::cout << "Hello world!\n"; // std::cout位于iostream库中
std::cout << "It is very nice to meet you!\n"; // 这些注释使得代码难以阅读
std::cout << "Yeah!\n"; // 尤其是当行的长度不同时

注释对齐

将注释放在代码行的右侧可以使代码和注释都难以阅读,特别是如果行很长的话。如果行比较短,可以简单地对齐注释(通常对齐到一个制表位),如下所示:

std::cout << "Hello world!\n";                 // std::cout位于iostream库中
std::cout << "It is very nice to meet you!\n"; // 这样更容易阅读
std::cout << "Yeah!\n";                        // 你不这么认为吗?

长行注释处理

然而,如果行很长,在右侧放置注释会使行变得非常长。在这种情况下,单行注释通常放在它注释的行上方:

// std::cout位于iostream库中
std::cout << "Hello world!\n";

// 这样更容易阅读
std::cout << "It is very nice to meet you!\n";

// 你不这么认为吗?
std::cout << "Yeah!\n";

作者注

在这个教程系列中,我们的例子属于以下类别之一:

  • 完整的程序(包含main()函数的那些)。这些已经准备好被编译和运行。
  • 代码片段(小块代码),如上面的语句。我们使用这些来简洁地演示特定的概念。

多行注释

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

多行注释的格式

/* 这是一个多行注释。
   这一行将被忽略。
   这一行也是。 */

美化多行注释

由于符号之间的所有内容都被忽略,你有时会看到程序员"美化"他们的多行注释:

/* 这是一个多行注释。
 * 左侧匹配的星号
 * 可以使这更容易阅读
 */

多行注释的限制

多行风格注释不能嵌套。因此,以下将有意外的结果:

/* 这是一个多行/*注释*/这不是在注释内部 */
// 上述注释在第一个*/结束,而不是第二个 */

正确使用注释

注释的三个主要用途

  1. 描述库、程序或函数的作用
  2. 描述代码将如何实现其目标
  3. 解释代码为什么要做某事

好的注释示例

// 这个程序根据学生的测试和家庭作业成绩计算最终成绩。
// 这个函数使用牛顿法来近似给定方程的根。
// 下面的行基于稀有度、等级和权重因子生成一个随机项目。

糟糕的注释示例

// 设置视野范围为0
sight = 0;

好的注释示例

// 玩家刚刚喝了一瓶失明药水,什么也看不见
sight = 0;

最佳实践

大量注释你的代码,并假设你正在对一个不知道代码做什么的人说话。不要假设你会记得为什么你做出了特定的选择。

关注公众号,回复"cpp-tutorial"

可领取价值199元的C++学习资料

公众号二维码

扫描上方二维码或搜索"cpp-tutorial"