1.7.1　怎样写好注释

要想把注释写好，有一条原则其实跟日常生活中的原则类似，也就是金发姑娘原则（Goldilocks Principle，又称古迪洛克原则），这条原则还有一个名字，即三只熊原则（Three Bears Principle），它来自“金发姑娘和三只熊”（Goldilocks and the Three Bear）这个童话故事。这条原则的关键在于：太多不行，太少也不行，要刚刚好才行。但所谓刚刚好（或者恰到好处）其实是个主观的说法，这得根据许多因素以及具体的情况来定。你必须凭借自己的判断力与经验，才能找到这个刚刚好的点。

下面是几条建议，可以帮助你在代码中写出良好的注释：

□假设阅读代码的人已经知道了这门语言的基本用法。你不是在教他们怎样用这门语言来编程。因此，显而易见的语言特性无须通过注释来解释。你应该解释的是代码里面不太容易看出来的地方。

□注释应该是一个完整的句子，因此，字母的大小写与标点符号的用法都需要注意。注释并不是普通的程序代码，它们是写给人看的，因此，为了读起来流畅易懂，你应该采用日常语言（而不是编程语言）的措辞来撰写注释。

□注释应该针对那些比较奇怪的用法而写。每一种编程语言都会有一些奇怪或者特殊的功能，这些功能可能不太常见，也可能以一种别人不易想到的方式得到应用，因此，有必要通过注释澄清你的用法。

□编写注释时要考虑到这段注释所针对的代码以后可能发生变化。代码经常会变，但针对该代码而写的注释却未必会同步地得到修改。为了不让代码与注释脱节，我们通常会针对某个函数或某一大块代码来撰写整体的注释，而不是专门针对其中的某几行代码分别撰写几条注释。这样的话，就算代码发生变化，我们写的注释也依然成立。大家在本书中会看到许多采用这种方式来撰写注释的例子。

□注释要写得宏观一些。你应该用注释来描述代码的意图，并说明这段代码是采用什么方式来解决问题的，而不是详细地描述它如何解决这个问题。这条原则跟上一条是相关的，这一条说的是要从宏观着眼，这样，即便代码的细节发生变化，我们所做的宏观描述也仍然有效。

□注释要表达出你自己的想法。撰写注释的时候，你应该尽量表达出自己写这段代码是想干什么，自己为什么要写这段代码，以及这段代码想要实现什么功能。至于这段代码实际上是怎样实现该功能的，只需要阅读代码本身而不用专门通过注释来描述）。

笔者在回顾自己6个月之前所写的代码时，经常会觉得奇怪，并且总是在问自己：“当时为什么要这样写？”“写到此处时我正在想什么？”。这些问题都意味着自己当初在这个地方写的注释太少了。另外，笔者在修改代码时，还经常要删掉许多与修改后的代码无关的注释，这种情况则意味着当初写的注释太多了，而且太过琐碎，不够宏观。另外还有一些注释是自己专门针对代码的意图（而不是具体的实现手法）来写的，这些注释就不需要在修改代码之后删掉（因为它们依然适用于新的代码）。

笔者曾经遇到这样一位程序员，他所写的注释跟该注释所针对的代码完全脱节。后来发现，这是因为他一开始采用了其中一种方式实现算法，并按照这种方式给算法的实现代码撰写了注释，而后他大幅修改了实现代码（但却没有同步地修改注释），从而导致留下来的注释与新版的实现代码无法匹配。于是，笔者只要在后续的代码里见到这位程序员的名字，就会仔细判断他所留下的注释是否跟刚才的情况类似，也就是同代码脱节，如果是，我通常就会直接将这段注释删掉。当然，笔者在这里只是举个例子，大家在审阅代码时不能轻率地删掉注释，除非你能确信这段注释确实跟它所针对的代码脱节了。

怎样写出有效的注释要花很长时间来学习。笔者并没有打算要求大家很快就掌握。你必须先学会观察代码，并练习写出自己容易看懂的注释，然后才谈得上如何写出别人也容易懂的注释，这需要花时间去培养。笔者在演示本书的各种C语言范例程序时会告诉你一些技巧，帮助你写出有用且灵活的注释。