1.2 注释

from http://www.learncpp.com/cpp-tutorial/12-comments/

注释的类型

注释是指一行或多行插入到源代码中用来解释说明代码做什么的文字。在C++中有两种注释类型。

//符号在单行注释的前面，它告诉编译器忽略后面的内容。例如：

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

 

一般,单行的注释是用来快速的注释单行的代码。

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

   2: cout << "It is very nice to meet you!" << endl; // these comments make the code hard to read

   3: cout << "Yeah!" << endl; // especially when lines are different lengths

将注释都放在代码行的右边会使得代码和注释都难于阅读，尤其当这行很长的时候。因此，//注释符通常放在行的上面。

   1: // cout and endl live in the iostream library

   2: cout << "Hello world!" << endl;

   3:  

   4: // this is much easier to read

   5: cout << "It is very nice to meet you!" << endl;

   6:  

   7: // don't you think so?

   8: cout << "Yeah!" << endl;

/*和*/成对的符号表示C风格的多行注释，任何处于两者之间的内容都将被忽略掉。

   1: /* This is a multi-line comment.

   2:    This line will be ignored.

   3:    So will this one. */

由于符号之间的内容都被忽略，你有时将会看到漂亮的注释：

   1: /* This is a multi-line comment.

   2:  * the matching asterisks to the left

   3:  * can make this easier to read

   4:  */

多行的注释不能是嵌套的。因此，下面就会出现不期望的结果：

   1: /* This is a multiline /* comment */ this is not inside the comment */

   2: //                                ^ comment ends here

不要将注释嵌套到其它注释中去。

 

注释的恰当使用

典型的，注释能够被使用在三个水平上。分别在库，程序，函数水平上。注释被用来描述库，程序或者函数做些什么。举个例子：

   1: // This program calculate the student's final grade based on his test and homework scores.

   2: // This function uses newton's method to approximate the root of a given equation.    

   3: // The following lines generate a random item based on rarity, level, and a weight factor.

上述所有的注释给读者很好的思路，在没有读实际代码的情况下理解代码将会做些什么。用户（可能是其他人，或是你，说不定哪天你会重新使用以前编写的代码）能够通过注释快速浏览得知这些代码是不是具有他或她想要实现的功能。挡在一个团队里面工作的时候这将会变得更加重要，并不是每个人都熟悉所有的代码。

其次，在上述提到的库，程序或是函数，注释应该被用来描述代码会怎样实现它的功能。

   1: /* To calculate the final grade, we sum all the weighted midterm and homework scores

   2:     and then divide by the number of scores to assign a percentage.  This percentage is

   3:     used to calculate a letter grade. */

 

   1: // To generate a random item, we're going to do the following:

   2: // 1) Put all of the items of the desired rarity on a list

   3: // 2) Calculate a probability for each item based on level and weight factor

   4: // 3) Choose a random number

   5: // 4) Figure out which item that random number corresponds to

   6: // 5) Return the appropriate item

 

在语句水平上，注释应该被用来描述代码为什么做这些事情。一个坏的语句注释解释代码做的是什么。如果你曾经写的代码是如此的复杂以至于需要解释一个语句是做什么的，那么你很有可能需要重新编写你的代码，而不是选择注释它。

这里有一些坏的行注释和好的行注释。

坏的注释：

   1: // Set sight range to 0

   2: sight = 0;

（是的，我们已经能够一眼看出，sight变量将被0赋值）

好的注释：

   1: // The player just drank a potion of blindness and can not see anything

   2: sight = 0;

 

（现在我们能够知道为什么sight被赋值为0了）

坏的注释：

   1: // Calculate the cost of the items

   2: cost = items / 2 * storePrice;

 

（是的，你能够明了这是计算价格的，但是为什么要除以2呢？）

好的注释：

   1: // We need to divide items by 2 here because they are bought in pairs

   2: cost = items / 2 * storePrice;

 

（现在，我们知道了）

程序员经常遇到在一个问题的多个方法之间做出艰难抉择的情况。而注释一个能够提醒你（或是告诉其他人）你为什么选择这个解决方案而不是其他解决方案的原因。

好的注释：

   1: // We decided to use a linked list instead of an array because

   2: // arrays do insertion too slowly.

   1: // We're going to use newton's method to find the root of a number because

   2: // there is no deterministic way to solve these equations.

 

最后，注释应该以一种帮助对于这些代码具体做什么没有概念的人更好的理解代码。对于这么件事情，程序员通常会说“它做什么是显而易见的！我是不会忘记这的！”猜猜会怎么样呢？它是不显而易见的，你会对于自己能够那么快忘记而感到非常吃惊。:) 你（或是其他人）会因为用人类的语言写下了你的代码是什么，怎么做，为什么写，而感谢你。阅读独立的一行代码是简单的。但是理解它们将要实现的目标确实困难的。

总结：

• *在库，程序，函数的水平上，描述的是什么。
• *在库，程序，函数内部，描述的是怎么做。
• *在语句水平上，描述的是为什么。

评论代码块

代码块的注释（临时的）有助于一下几个方面：

1) 你正在编写一片没有编译的新的代码，同时你需要运行你的程序。如果编译出现错误，编译器会组织你的运行。代码块的注释能够允许你的程序通过编译而运行

2) 你想要通过注释一些代码行来改变你的程序的运行方式。举个例子，你认为一个特殊的函数调用使你的程序崩溃了。块注释掉你的函数调用，然后执行你的程序，看是这个函数否否是主要原因。

在我们即将到来的例子中，我们建议使用Visual Studio Express的用户，在他们需要运行程序的时候需要#include "stdafx.h"。但是，我们通常注释掉这行代码，因为在其它编译器上会导致错误。Visual Studio Express用户在进行编译的时候，必须去注释这一行。