翻译：C++注释。大概要几天才能完全翻译

1.2 — 注释

注释的类型

一个注释是用来解释代码的，可以是一行或者是几行。

符号“//”开头的是单行注释，编译器会忽略这个符号到行尾的所有内容。

1	std :: cout << "Hello world!" << std :: endl ; //从这里到右边的一切内容都被忽略了。

单行注释一般用于解释单行代码。

1 2 3

std :: cout << "Hello world!" << std :: endl ; // cout和endl在iostream库里 std :: cout << "It is very nice to meet you!" << std :: endl ; // 这些注释使得代码难以读取 std :: cout << "Yeah!" << std :: endl ; // 特别是当每行代码的长度不一样时

对行的右侧进行注释会使代码和注释难以阅读，特别是行很长的时候。因此，//注释通常位于代码的上方。

1 2 3 4 5 6 7 8

// cout和endl在iostream库里 std :: cout << "Hello world!" << std :: endl ;   // 这下读取这些代码简单多了 std :: cout << "It is very nice to meet you!" << std :: endl ;   // 你觉得呢? std :: cout << "Yeah!" << std :: endl ;

符号/*和*/是段注释的起始符和终止符。它们之间的所有内容将被忽略。

1 2 3

/* 这是一个段注释。    这行的内容将被忽略。    这一行也一样。 */

因为任何在这两个符号之间的内容都会被忽略，所以你也可以这样“美化”你的注释：

1 2 3 4

/* 这是一个段注释。 * 符号'*'在同一列内， * 可以让你更容易读。 */

然而，段注释不能嵌套，所以以下代码不会产生你预料中的结果：

1 2	/* 这是一个 /* 段注释 */ 这个地方没有被注释 * / // 上面的注释在第一个'*/'结束了, 而不是第二个 '*/'

所以，永远不要在段注释中嵌套段注释。

/* 下面这个区域不在原文内，只是我提的一些建议。

在注释一段代码的时候，可以采用#if 0 和 #endif 以防止段注释嵌套。

*/

正确地使用注释

通常，注释用于解释一个库、一个程序或者一个函数。比如：

1	// 这个程序计算一个学生测试和作业的成绩。

1	// 这个函数用来逼近给定的等式的根。

1	// 以下代码用于生成随机项。

所有这些注释都能让读者很好地了解该程序试图完成的任务，而无需查看实际的代码。用户（可能是其他人，或者如果您试图重复使用之前编写的代码），可以一眼就能看出代码是否与他想要完成的工作相关。当作为一个团队的一部分工作时，这是非常重要的，并不是每个人都会熟悉所有的代码。

其次，在上述库，程序或函数中，可以使用注释来描述代码如何实现其目标。

（省略两个代码块）

要注释代码，应该是有意义的内容，而不是简单地解释什么代码干了什么。

以下是一些好的注释和糟糕的注释的事例：

糟糕的注释：

1 2	// 把变量sight设为0 sight = 0 ;

(废话！我们已经知道了这行代码要把sight设为0)

好的注释：

1 2	// 玩家喝了一瓶失明药水因此看不到任何东西 sight = 0 ;

(现在我们知道这是为什么了)

糟糕的注释:

1 2	// 计算这些物品的总价 cost = items / 2 * storePrice ;

(是的，我们可以知道这是一个成本计算，可是为什么要除以2？)

好的注释：

1 2	// 我们需要将项目数除以2因为它们是成双买的 cost = items / 2 * storePrice ;

(现在我们知道了！)

注释是提醒自己（或告诉其他人）你做出一个觉得而不是另外一个决定的原因的好方法。

好的注释：

1 2	// 我们决定用链表实现而不是用数组是因为 // 数组的插入过程太慢。

1 2	// 我们将要用牛顿的方法找到一个数字的根是因为 // 没有其他合适的方法

Finally, comments should be written in a way that makes sense to someone who has no idea what the code does. It is often the case that a programmer will say “It’s obvious what this does! There’s no way I’ll forget about this”. Guess what? It’s not obvious, and you will be amazed how quickly you forget.

You (or someone else) will thank you later for writing down the what, how, and why of your code in human language. Reading individual lines of code is easy. Understanding what goal they are meant to accomplish is not.

To summarize:

• At the library, program, or function level, describe what
• Inside the library, program, or function, describe how
• At the statement level, describe why.

Commenting out code

Converting one or more lines of code into a comment is called commenting out your code. This provides a convenient way to (temporarily) exclude parts of your code from being included in your compiled program.

To comment out a single line of code, simply use the // style comment to turn a line of code into a comment temporarily:

Uncommented out:

1	std :: cout << 1 ;

Commented out:

1	//    std::cout << 1;

To comment out a block of code, use // on multiple lines of code, or the /* */ style comment to turn the block of code into a comment temporarily.

Uncommented out:

1 2 3

std :: cout << 1 ;      std :: cout << 2 ;      std :: cout << 3 ;

Commented out:

1 2 3

//    std::cout << 1; //    std::cout << 2; //    std::cout << 3;

or

1 2 3 4 5

/*     std::cout << 1;     std::cout << 2;     std::cout << 3; */

There are quite a few reasons you might want to do this:

1) You’re working on a new piece of code that won’t compile yet, and you need to run the program. The compiler won’t let you run if there are compiler errors. Commenting out the code that won’t compile will allow the program to compile so you can run it. When you’re ready, you can uncomment the code, and continue working on it.

2) You’ve written code that compiles but doesn’t work correctly, and you don’t have time to fix it until later. Commenting out the broken code will ensure the broken code doesn’t execute and cause problems until you can fix it.

3) To find the source of an error. If a program isn’t producing the desired results (or is crashing), it can be useful in some cases to disable parts of your code to see if you can isolate what’s causing it to not work correctly. If you comment out one or more lines of code, and your program starts working as expected (or stops crashing), odds are whatever you last commented out was part of the problem. You can then investigate why those lines of code are causing the problem.

4) You want to replace one piece of code with another piece of code. Instead of just deleting the original code, you can comment it out and leave it there for reference until you’re sure your new code works properly. Once you are sure your new code is working, you can remove the old commented out code. If you can’t get your new code to work, you can always delete the new code and uncomment the old code to revert back to what you had before.

Commenting out code is a common thing to do while developing, so many IDEs provide support for commenting out a highlighted section of code. How you access this functionality varies by IDE (in Visual Studio, you can find it in the Edit menu under Edit->Advanced->Comment Selection/Uncomment Selection).

A note on comments in these tutorials

Throughout the rest of this tutorial series, I’ll be using comments inside code blocks to help illustrate how things work. Astute readers will note that by the above standards, most of these comments are horrible. 

As you read through the rest of the tutorials, keep in mind that the comments are serving an intentional educational purpose, not trying to demonstrate what good comments look like.