包教包会!C语言 第二课 为程序写注释可以延缓秃顶!
写注释以便以后更好地理解程序
编写良好代码的很多要素在于以一种一致的方式编写代码。一致性使读者（或您）更容易在以后的某个时间理解代码。一致性通常是一件好事。然而，在编写代码时，可能会有需要跳出这种一致性的情况，有些很好的原因，当我们编写的代码变得特别扭曲或晦涩难懂时。或者，我们可能会以某种方式编写代码，这种方式可能不明显或可能不被期望，再次出于很好的原因。在这些情况下，我们应该注释我们的代码 - 不是为编译器，而是为我们自己和其他可能会阅读我们的代码的人，通常是很久以后，他们会抓住他们的头皮想着，“什么？我/他们打算在这里做什么？”
代码注释是解释为什么以某种方式编写特定代码的一种方式。让我们探讨一些在C中编写代码注释的不同方式。
当正确使用时，代码中的注释会被编译器忽略。它们只是为了让人理解。考虑以下代码注释：
/* (1) 单行 C 风格注释。*/
/* (2) 多行
C 风格注释。*/
/*
* (3) 很常见的方式来
* 格式化多行
* C 风格注释。
*/
/* (4) C 风格注释可以出现在几乎任何地方。*/
/*(5)*/ printf( /* Say hello. */ "Hello, world!\n" );
/*(6)*/ printf( "Hello, world!\n" ); /* Yay! */
// (7) C++ 风格注释（由行尾结束）。
printf( "Hello, world!\n" ); // (8) Say hello; yay!
//
// (9) 一种更常见的多行注释方式
//
// (10) 任何东西都可以出现在 // 后面，包括 /* ... */ 和
// 即使是第一个 // 后面还有更多 //，它们也会被忽略，因为它们都在注释中。
前面代码中的注释并不是特别有用的注释，但它们展示了 C 语言中注释的各种用法。
代码中的注释，如果做得正确，编译器会忽略它们，它们只是为了人类理解而存在的。下面是一些示例注释：
/* (1) 单行C风格的注释。 /
/* (2) 多行C风格的注释。
这是第一行。*/
这是第二行。 */
/*
(3) 多行C风格注释的常见格式。
*这是第一行。
*这是第二行。
/
/ (4) C风格的注释可以出现在几乎任何地方。/
/(5)/ printf( / 说Hello。 / "Hello, world!\n" );
/(6)/ printf( "Hello, world!\n" ); / Yay! /
// (7) C++风格的注释（以行尾结束）。
printf( "Hello, world!\n" ); // (8) 说Hello；耶！
//
// (9) 更常见的方式
// 用多行C++风格的注释
//
// (10) 在//之后可以出现任何内容，甚至/...*/，以及更多的//，但它们都将被忽略，因为它们都在注释中。
上述代码中的注释并不是特别有用的注释，但它们展示了在C中注释的各种使用方式。
带有标记（1）-（6）的注释是旧式C注释。对于这些注释的规则很简单-当遇到/ 时，它是一个注释，直到后续遇到 /，无论它是否出现在同一行或几行之后。/ （中间有空格）和 /（中间有空格）不是有效的注释指示符。
从标记（7）到（10）显示了从C++中采用的C注释。当遇到//时，它是一个注释，直到遇到行尾（EOL）。因此，这些注释不能像C注释那样随意出现。同样，/ /（中间有空格）不是有效的注释指示符。
C注释更加灵活，而C++风格的注释更加明显。这两种风格都很有用。在本书中，我们将使用两种风格的注释。
现在我们知道了各种格式化注释的方式，让我们考虑一些有效的使用注释的方式。
代码注释的一些指导原则
代码注释的最佳指导原则之一是生活中要遵循的同样的原则。这有时被称为Goldilocks原则，也被称为Three Bears原则，取自童话故事《Goldilocks and the Three Bears》。这个指导原则的实质是不要太多，不要太少，刚刚好。然而，刚刚好是主观的，它取决于几个
o 高层次的注释：描述代码的意图和它尝试解决问题的方式。这个准则与我们提到的第一个准则密切相关。注释越高层次地描述，随着代码的变化，它们需要被修改的可能性就越小。 o 传达您的意图：通过您的注释，努力传达您所编写的代码的意图，为什么需要代码，以及代码试图实现什么。代码实际上在做什么应该来自于代码本身。 我经常会惊讶地发现，我在6个月前编写的代码，现在回过头来看时会感到困惑。往往情况是我会挠头问自己为什么要这样做？或者我当时在想什么？（这两种情况都是因为注释太少）。我还发现，当我更改代码时，我必须删除许多不再必要的注释（这是注释太多的情况）。
当我关注代码的意图时（我在这里试图做什么），很少会发现我注释太多的情况。 在我的职业生涯中，曾经遇到过一位程序员，他的注释与实际代码完全脱节。我得出的结论是，这个程序员最初打算让他们的算法以某种方式工作，但是后来修改了代码，以至于注释不再与实际代码匹配。
当我在以后的代码中看到该程序员的姓名时，经过仔细检查，我就会删除代码注释，因为我发现它们是不相关的。除非您绝对确定自己理解代码并且注释与代码不匹配，请不要这样做。 学习如何有效地注释代码是一个终身的挑战。我不认为您会很快学会这个。您需要通过多年的检查代码，让您的代码更清晰，让您自己更清晰，更清晰地向其他人展示您的代码。当我们一起学习各种 C 示例程序时，我打算展示各种有用和坚韧的注释技术。 向“Hello, world!”程序添加注释 现在，我们已经探讨了各种注释代码和注释风格的方式，让我们将hello1.c复制到hello2.c，并添加适当的注释。
你可以使用命令解释器将hello1.c复制到hello2.c，也可以在编辑器中打开hello1.c并立即将其保存为hello2.c。无论你如何操作，你应该将hello1.c和hello2.c都放在Chapter1_HelloWorld目录下。在编辑器中修改hello2.c，使其显示如下所示：
/*
hello2.c
My first C program with comments.
by <你的名字>
created yyyy/mm/dd
*/
#include <stdio.h>
int main()
{
printf( "Hello, world!\n" );
return 0;
}
/* eof */
注意，每行以*字符开头提供注释，说明该组有多行注释。该组以/开始，并最终以/结束。编译、运行并验证该程序。确保你没有意外地在这里或那里引入字符，这是常见的错误，应该总是进行验证。
请注意，每行开头带有注释的 * 字符表明这是一组多行注释；该组以 /* 开始，最终以 */ 结束。编译、运行并验证此程序。确保您没有引入任何意外字符，这是可能的，也应该经常进行验证。
现在，这是一个完整的程序。从 hello1.c 提供的证据来看，该程序是正确的——它以我们所期望的方式显示了我们的信息。前六行注释提供了有关程序作者和编写日期的最少信息。这个程序的标题信息可以简单，也可以更为详细。现在，我们将保持此类标题信息的简单。
这个程序本身非常简单，任何了解 C 的人都知道它打印了一个简单的消息。这里不需要进一步的注释。
最后，我们用注释标记文件的结尾；这种标记的唯一好处是当有多个编辑器窗口打开和/或程序变得非常长时。这种简单的分界线让我们知道我们已经到了 EOF。这个最终的 EOF 指示符完全是可选的，更多是一种风格偏好，而不是一种具有严格理性的做法。
我发现，在我使用的每一种编程语言中，我的注释风格都会适应给定语言的简单或晦涩难懂程度。当我在大学里编写汇编语言程序或稍后使用 Fortran 4 的早期版本时，我几乎在每一行上都进行了注释。然而，对于 C++ 或 Objective-C，我发现我只是零星地或在注释块中进行注释，这些注释块解释一个概念或编程解决方案。
此外，即使在给定语言内，当要解决的问题不寻常或者我正在使用新的方法来解决问题时，也需要更多的注释。
在本书的其余部分，根据代码示例，我们将探讨各种有用的注释实践，即使代码可能会更改，这些实践也是有效的。