方法

38，检查参数的有效性

• 你应该在文档中清楚地指明所有的参数限制，并且在方法的开头处检查参数，以强制施加这些限制。
• 对于共有的方法，要用javadoc的@throw标签在文档中说明违反参数限制时会抛出的异常。
  一旦在文档中记录了对方法参数的限制，并且记录了一旦违反这些限制将要抛出的异常，强加这些限制就是非常简单的事了。
• 非共有方法通常应该用断言（assertion）来检查它们的参数。如：assert a!= null;
• 有些时候，有效检查工作非常昂贵，或者根本不切实际的，并且有效性检查已隐含在计算过程中完成。
• 不要从本条目的内容中得到这样的结论：对任何参数的限制都是件好事。相反，在设计方法时，应该使它们尽量通用，并符合实际需要。

39，必要时进行保护性拷贝

保护性拷贝是在检查参数有效性之前进行的，并且有效性检查是针对拷贝之后的对象，而不是针对原始对象。

40，谨慎设计方法签名

• 谨慎地选择方法名称。首要目标是易于理解，并且与同一包中的其他名称风格一致的名称；第二个目标应该是选择与大众认可的名称相一致的名称。
• 不要过于追求提供便利的方法。对于类和接口所支持的每个动作，都提供一个功能齐全的方法。只有当意向操作被经常用到的时候。才考虑为它提供快捷方法。如果不能确定，还是不提供快捷方法为好。

方法太多会使类难以学习，使用，文档化，测试和维护。使接口实现者和接口用户的工作变得复杂起来。

• 避免过长的参数列表。目标是四个参数，或者更少。相同类型的长参数序列格外有害。

有三种方法可以缩短过长的参数列表：第一种是把方法分为多个方法，每个方法只需要这些参数的一个子集。（这样可能导致方法过多，但可以通过提升他们的正交性，还可以减少方法的数目）；第二种方法是创建辅助类，用来保存参数的分组。（这些辅助类一般为静态成员类）；第三种是从对象构建到方法调用都采用Builder模式

• 对于参数类型，要优先使用接口而不是类。如果使用类而不是接口，则限制了客户端只能传入特定的实现。

• 对于boolean参数，要优先使用两个元素的枚举类型。它使代码更易于阅读和编写。

41，慎用重载

对于重载方法的选择是静态的，而对于被覆盖的方法的选择是动态的。

胡乱的使用重载，会使程序员陷入到：对于任何一组实际参数，哪个重载方法是使用的疑问中。

对于方法可以给方法取不同的名称；对于构造器你没有使用不同名称的机会，但可以使用静态工厂。

简而言之，能重载的方法并不意味着就应该重载方法。一般情况下，对于具有多个相同参数数目的方法来说，应该避免重载方法。传递同样的参数，所有的重载方法的行为必须一致，否则会使程序员难以理解。

42，慎用可变参数

可变参数方法接受0个或者多个指定类型的参数。可变参数机制通过创建一个数组，数组的大小为在调用位置所传递的参数数量，然后将参数值传到数组中，最后将这个数组传给方法。

不必改造具有final数组参数的每个方法；只当确实是在数量不定的值上执行调用时才使用可变参数。

在重视性能的情况下，要注意可变参数每次调用都会导致进行一次数组分配和初始化。如果凭经验确定无法承受这一成本，但又需要可变参数的灵活性。假设确定95%的调用会有3个参数或者更少，就声明该方法的重载，当参数数目超过3个时，就使用一个可变参数方法。（EnumSet类）

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

对于返回null，几乎每次用到改方法时都要特殊处理下null，这样很容易出错，程序员会忘了进行处理，也不容易找到。

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

如果想要使一个API真正可用，必须为其编写文档。

为了正确地编写API文档，必须在每个被导出的类，接口，构造器，方法和域声明前增加一个文档注释。如果类时可序列化，也应该对它的序列化形式编写文档。

方法的文档注释应该简洁地描述出它和客户端之间的约定。这个方法做了什么，所有的前提条件和后置条件，它的副作用。

每个文档的第一句成了该注释所属元素的概要描述。同一个类或者接口中指定位置上的成员或构造器，不应该具有相同的概要描述。

• 对于方法和构造器而言，概要描述应该是个完整的动词短语（包含对象），它描述该方法所执行的动作。
• 对于类，接口和域，概要描述应该是一个名词短语，它描述了改类或接口的实例，或者域本身所代表的事物。
• 当为泛型或者方法编写文档时，确保要在文档中说明所有的类型参数。
• 当为枚举类型编写文档时，要确保在文档中说明常量，以及类型，还有任何共有的方法。
• 为注解类型编写文档时，要确保在文档中说明所有成员，以及类型本身。
• 线程安全和可序列化要在文档中说明。
• 可以利用{inheritDoc}标签从超类型中继承文档的注释的部分内容。