13.1 挑选约定

编写注释的第一步是确定注释的约定，例如你将注释什么以及你将用于注释的格式。 如果你正在使用的编程语言带有文档编译工具，例如用于 Java 的 Javadoc、用于 C++ 的 Doxygen 或用于 Go 的 godoc，请遵循这些工具的约定。 这些约定都不是完美的，但这些工具提供了足够的好处来弥补这一点。 如果你在一个没有现成约定可循的环境中编程，试着采用一些其他类似的语言或项目中的约定；这将使其他开发者更容易理解和遵守你的约定。

约定有两个目的。首先，它们确保一致性，这使得注释更容易阅读和理解。其次，它们有助于确保你确实在写注释。如果你对于要注释什么内容以及如何写注释没有一个明确的想法，最后的结果往往就是没有写注释。

大多数注释属于以下几类之一：

• 接口：紧接在一个模块声明之前的注释块，例如类、数据结构、函数或方法。这种注释描述的是模块的接口。对于一个类，注释描述了该类提供的整体抽象。对于一个方法或函数，注释描述了它的整体行为、它的参数和返回值（如果有的话）、它产生的任何副作用或异常，以及调用者在调用该方法之前必须满足的任何其他要求。

• 数据结构成员：数据结构中字段声明旁边的注释，例如类的实例变量或静态变量。

• 实现注释：方法或函数代码内部的注释，描述代码内部如何工作。

• 跨模块注释：描述跨模块依赖关系的注释。

最重要的注释是前两类。 每个类都应该有一个接口注释，每个类变量都应该有一个注释，每个方法都应该有一个接口注释。 偶尔，某个变量或方法的声明是如此明显，以至于没法向注释中添加任何有用的东西（getter 和 setter 有时就属于这种情况），但这种情况很少； 与其花精力担心是否需要注释，不如对所有内容进行注释。实现注释通常是不必要的（见下文第13.6节）。跨模块的注释是最罕见的，而且写起来也很麻烦，但在需要用到的时候，它们是相当重要的；第13.7节更详细地讨论了它们。