注释应该描述那些在代码中不明显的东西

编写注释的原因是，编程语言中的语句无法捕获开发人员在编写代码时头脑中的所有重要信息。 注释记录了这些信息，以便后来的开发人员可以轻松地理解和修改代码。 注释的指导原则是，注释应该描述那些在代码中不明显的东西。

有很多东西从代码中是不能明显看出来的。有时是低层次的细节不明显。例如，当我们使用一对索引描述一个范围时，索引指向的元素是在范围内还是在范围外，这并不明显。有时并不清楚为什么需要某段代码，或者它为什么以特定的方式实现。有时，开发人员会遵循一些规则，比如“总是在b之前调用a”。你也许可以通过查看所有的代码来猜测规则，但这是很痛苦的，而且容易出错；注释可以使规则清晰明了。

注释的最重要原因之一是抽象，其中包含许多从代码中看不出来的信息。抽象的概念是提供一种简单的思考方式，但代码是非常详细的，以至于仅通过阅读代码很难看出抽象。 注释可以提供更简单、更高层次的视角（“在这个方法被调用后，网络流量将被限制在每秒maxBandwidth字节”）。 即使这些信息可以通过阅读代码推导出来，我们也不想强迫模块的用户这样做：阅读代码很费时间，而且强迫他们考虑很多在使用模块时不需要的信息。开发人员应当能够理解一个模块提供的抽象，而无需阅读除了外部可见的声明之外的任何代码。 做到这一点的唯一方法是用注释来补充声明。

本章讨论了哪些信息需要在注释中描述，以及如何写好注释。正如你将看到的，好的注释通常以与代码不同的详细程度来解释事情，在某些情况下更详细，而在其他情况下则不那么详细（更抽象）。