Effective Java读书笔记十六(Java Tips.Day.16)

TIP 42 慎用可变参数

在需要定义参数熟不定的方法时，可变参数方法时一种很方便的方式，但他们不应该被滥用。

这里有几个通常的建议：

• 如果可能，请将第一个参数定义为int类型，表示数组长度。
• 使用可变参数会带来额外的性能开销。因为每次调用时，都会进行一次数组分配和初始化。
• 如果不想承受额外的性能开销，可以重载方法，每个重载版本的参数数量分别为1, 2, 3，最后再提供一个可变参数的版本。因为使用超过4个参数的情况并不多，在大部分情况下，可以避免可变参数带来的额外开销。

---

TIP 43 返回零长度的数组或集合，而不是null

在方法中进行参数检查时，最常见的是做null检查。而最常见的错误，往往也是因为没有捕捉 NullPointException 这个异常。

而当你要返回一个数组或集合时，如果它们不包含任何一个元素，你应当返回长度为0的数组或集合。
这样可以避免在方法调用时，需要对其返回值做额外的检查。

返回数组或集合的方法，没有任何理由返回null，而不是返回一个零长度的数组和集合。

---

TIP 44 为所有导出的API元素编写文档注释

Java提供了JavaDoc，从而使生成文档变得很容易，它可以利用特殊的文档注释，根据源代码自动生成API文档。为此，以下子条目可供参考：

• 在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。
• 对于可序列化类，也应该对它的序列化形式编写文档。
• 文档注释应当简洁地描述它和客户端之间的约定。
• 对于方法，应列出前置条件、参数、返回值、后置条件、副作用。
• 可以使用HTML标签，但HTML字符需要经过转义。

总之，如果要为API编写文档，使用JavaDoc文档注释是最好，最有用的途径。
而具体的方法和规范，请参阅Sun的《How to Write Doc Comments》。