本书中的例子并不能成为产品代码充分注释的典范（否则，这书就不是一本，而是三本了）。但是，注释，尤其是接口中的注释，是开发过程中的一个重要组成部分。

将接口记录成文档，以供其他开发者使用；除接口的设计者之外，每个接口至少要经过一个其他开发者的审查。

为了想明白为什么由另一开发者审查接口会很有价值，不妨把自己放在用户或测试工程师的位置上试着理解你所编写的类。你很清楚如何使用你所编写的接口——毕竟，这个接口是你设计的！你当然觉得为成员函数所提供的简短名字是“明显的”和“不言自明的”。但事实是，除非你已经花很长时间让其他人检查你的接口和文档，否则仍有巨大的改进空间——特别是在可用性方面。

可用性很大一部分是指能够获得一个不熟悉的头文件并开始使用这个头文件。在实践中，头文件注释常常是为接口编写的唯一文档（或至少是唯一的最新文档）。如果用户被迫窥视实现，以便弄清楚如何使用你所编写的组件，那么它就不是编写良好的文档。

明确给出未定义行为出现的条件。

文档的另一个重要方面是要在行为未定义的情况下，明确地标识条件。请看下面的声明：


 

你认为函数fact的注释怎么样？我们可能猜测fact应该是普通数学函数阶乘factorial(n!)，fact(0)实际上是1，而不是1?0=0或者未定义。然而，该注释并没有说明这些情况。该注释没有说明当n是非正数时，情况会如何。

阶乘对于负整数值是未定义的。在这些情况下，我们的特定实现将返回0。当n的值是负数时，fact(n)的返回值依实现而定，而不是规格说明书的一部分，必须明确告知用户不能依赖这种行为。另一种替代该实现的实现很容易对n的负值提供不同的行为（包括引起你所编写的程序崩溃的值）。

一般来说，除非明确地在我们编写的注释中声明，否则用户和测试工程师将没有办法区分什么是想要或必需的行为，什么是仅由特定的实现选择产生的巧合行为。下面提出一个更好的、更可用的接口：


 

未能明确地解说未定义行为的条件，会不经意地让软件支持一些无关的行为，这些行为可能会影响系统的性能或限制实现的方式。如果一个测试工程师不够机警，你可能会发现自己的实现方式产生的无关行为会被一套明确针对那些行为的回归测试无情地击中。更糟糕的是，通过不适当地（或无意识地）使用，用户可能会渐渐地依赖这种巧合的行为。

实现代码时，使用assert语句有助于对假设条件编写文档。

为了检测逻辑错误将错误检测贯穿系统每个层次，会使成本变得昂贵，大型系统中尤其如此。优秀的文档可以作为一种可行选择替代编写过多的代码的。例如，有些软件开发者认为处理进入一个函数的每个指针是必要的，即使那个指针是空的。如果这个函数是一种广泛使用的接口的一部分，完全可以证明这是一个支持鲁棒性的正确决定。或者，在函数实现的开头用assert语句判断指针是否为空，并告知用户传入空指针会产生未定义行为，这样做足以保证程序的鲁棒性：


 

文档和assert语句的有效使用，可以让代码更轻巧并仍然很实用。如果有人误用了函数，这是他们自己的失误——而且他们将会很快发现这个错误！

如果每个开发人员总是清楚地说明代码的行为限制（例如，一个函数的指针参数不能为空）这将是值得称道的。当然，尽责的用户，不会向函数传递空指针，除非该函数已明确说明了对于空指针所产生的行为。