13.6 实现注释：是什么和为什么，而不是怎么做

实现注释是出现在方法内部的注释，以帮助读者理解方法的内部工作方式。大多数方法都非常简短，不需要任何实现注释：有了代码和接口注释，很容易就能弄清楚方法是如何工作的。

实现注释的主要目的是帮助读者理解代码在做什么（而不是如何做）。一旦读者知道了代码要做什么，通常就很容易理解代码的工作原理。对于短的方法，代码只做一件事，这在其接口注释中已经描述过了，所以不需要实现注释。较长的方法有几个代码块，作为该方法整体任务的一部分，做不同的事情。在每个主要的代码块之前添加一个注释，对该代码块所做的事情进行高层次（更抽象）的描述。下面是一个例子：

// Phase 1: Scan active RPCs to see if any have completed.

对于循环，在循环之前添加注释来描述每次迭代中发生的情况会很有帮助：

// Each iteration of the following loop extracts one request from 
// the request message, increments the corresponding object, and 
// appends a response to the response message.

请注意这个注释是如何在一个更抽象和直观的层面上描述循环的；它没有涉及任何关于如何从请求消息中提取请求或对象如何被递增的细节。循环注释只需要用于较长或较复杂的循环，在这种情况下，循环在做什么可能并不明显；许多循环很短，很简单，其行为已经很明显了。

除了描述代码在做什么（what）之外，实现注释也有助于解释为什么（why）。如果代码中存在一些通过阅读代码并不明显的棘手的方面，则应将它们记录下来。例如，如果一个bug修复需要添加一些目的并不完全明显的代码，请添加描述为什么需要该代码的注释。对于有一个写得很好的描述问题的错误报告的bug修复，注释可以引用bug跟踪数据库中的问题，而不是重复它的所有细节（“修复RAM-436，与Linux 2.4.x中的设备驱动崩溃有关”）。开发人员可以在bug数据库中寻找更多的细节（这是避免注释中重复的一个例子，将在第16章中讨论）。

对于较长的方法，为几个最重要的局部变量写注释可能会有帮助。然而，大多数局部变量如果有好的命名就不需要文档。如果一个变量的所有用途都能在几行之内看到，那么通常不需要注释就能很容易地理解这个变量的用途。在这种情况下，让读者阅读代码来理解变量的含义是可以的。然而，如果该变量在代码中使用的跨度很大，那么你应该考虑添加一个注释来描述该变量。在记录变量时，要关注变量代表什么，而不是它在代码中的操作方式。