C++ 自学教程 LearnCPP 第1.2章注释语句

本文详细介绍了C++中的注释用法，包括单行注释和多行注释的特点及应用技巧，并给出了如何撰写有效注释的建议。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

C++ 自学教程第1.2章注释语句

前言：这一章节讲如何注释你的程序。有些例子的注释代码的颜色好像有点问题，我试着调整了一下好像还是不是很清楚。大家多包涵。

注释的种类

注释（comment）是在源代码中解释代码的一行或多行文本。在C++中主要有两种注释。

//符号在C++被用于引入单行注释。编译器会忽略//符号后的所有内容。比方说

std::cout << "Hello world!" << std::endl; // Everything from here to the right is ignored.

通常情况下，单行注释被用于快速标注单行代码。

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

把注释放在代码右侧加大了阅读代码跟注释的难度，尤其是如果这一行很长的话。所以单行注释常被放在它所注解的代码上方。

// cout and endl live in the iostream library
std::cout << "Hello world!" << std::endl;

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

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

/* 和 */ 符号可以被用作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 program calculate the student's final grade based on his 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.  This percentage 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

// 为得到随机项，我们会完成以下几个步骤：
//1) 把所有稀有项放置在一个列表中。
//2) 基于等级和权重因子，为每一项计算相应概率。
//3)生成一个随机数。
//4)查找出这个随机数的对应项。
//5)返回这个相应的随机项。

这些注释为阅读者总结了代码的大致运行流程。

在叙述语句层级，一个好注释应该解释为什么这行代码这么做，而一个差注释解释代码在做什么。如果你的代码已经复杂到需要解释某个独立语句在做什么，那你可能需要重写你的代码，而不是注释它。
下面举几个例子：
差注释：

// Set sight range to 0
sight = 0;

//将sight设为0
（是，我们当然能看懂变量sight被赋值为0了，又不瞎= =）

好注释：

// The player just drank a potion of blindness and can not see anything
//玩家刚刚服下了失明的毒药，现在什么都看不清
sight = 0;

（现在我们明白为什么sight被赋值成了0）

差注释：

// Calculate the cost of the items
//计算物品的价格
cost = items / 2 * storePrice;

（是，我们能看到等式左侧是价格，但是为毛要除二啊？）

好注释：

// We need to divide items by 2 here because they are bought in pairs
//价格需要除以二因为我们是成对购买的
cost = items / 2 * storePrice;

（懂了！）

程序员常常要想破脑袋决定是这么解决问题，还是那么解决问题。注释可以很好的帮助你回忆（或者告诉别人）为什么你这么解。

好注释：

// We decided to use a linked list instead of an array because
// arrays do insertion too slowly.
//我们决定用连接的列表而不是数列，因为在数列中添加补充项很慢。

最后，写注释时，应该把阅读对象设为对你的程序一无所知的读者。程序员们常常会说“这代码明显是在做这个！我不可能忘记怎么用的。”结果你猜怎么着？根本没那么简单。你会惊讶于自己会多快速的忘记自己的代码在做什么。你自己（或他人）会日后对写下这些解释“是什么，怎样做，为什么这么做”的注释的自己感激涕零。理解单独几行代码容易，理解他们最终的目的并不简单。

总结一下：

在高层级，也就是对库，程序，或者函数的注释，解释是什么
在库，程序，或者函数的代码中的注释，解释怎么做
对低层级，也就是叙述语句的注释，解释为什么

注释掉一段代码

注释掉代码也就是将某段代码转换为注释。这其实是临时将某段代码从你的程序中暂时移除的好方法。

想要暂时掉注释某行代码，使用//符号即可。
未被注释：

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。

注意：后续教程会给出很多代码以及其注释。聪慧的读者可能会发现其中很多注释都不是我今天所说的好注释，那是因为这些注释的目的是帮助读者学习编程而不是在解释这段程序。

说明：这系列笔记是基于网上一个英文教程LearnCPP