《Effective Java》知识点（7）--方法

49. 检查参数的有效性

       每当编写方法或者构造器的时候，应该考虑它的参数有哪些限制。应该把这些限制写到文档中，并且在这个方法体的开头处，通过显式的检查来实施这些限制。

       没有验证参数的有效性，可能导致违背失败原子性(failure atomicity)。

       对于公有的和受保护的方法，要用Javadoc的@throws标签在文档中说明违反参数值限制时会抛出的异常。非公有的方法通常应该使用断言来检查它们的参数。

50. 必要时进行保护性拷贝

       如果一个类包含有从客户端得到或者返回到客户端的可变组件，这个类就必须保护性地拷贝这些组件。如果拷贝成本受到限制，并且信任它的客户端不会不恰当地修改组件，就可以在文档中指明客户端的职责是不得修改受到影响的组件，以此来代替保护性拷贝。

       应该假设类的客户端会尽其所能来破坏这个类的约束条件，因此必须保护性地设计程序。

       Date已经过时，不应该在新代码中使用，应该使用Instant。

       对于构造器的每个可变参数进行保护性拷贝(defensive copy)是必要的。

       对于参数类型可以被不可信任方子类化的参数，不要使用clone方法进行保护性拷贝。

51. 谨慎设计方法签名

      a. 谨慎地选择方法的名称。应该遵循标准的命名习惯。

      b. 不要过于追求提供便利的方法。 只有当一项操作被经常用到时，才考虑提供快捷方式。

      c. 避免过长的参数列表。目标是四个参数或更少。缩短参数列表的3种方法：

第一种是把一个方法分解成多个方法。第二种是创建辅助类。第三种是从对象构建到方法调用都采用Builder模式。

       d. 对于参数类型，要优先使用接口而不是类。

       e. 对于boolean参数，要优先使用两个元素的枚举类型。

52. 慎用重载

       对于重载方法的选择是静态的，要调用哪个重载方法是在编译时决定的。而对于被覆盖的方法的选择是动态的。

       安全而保守的策略是永远不要导出两个具有相同参数目的的重载方法，即尽量避免重载方法。

       不要在相同的参数位置调用带有不同函数接口的方法。

       当传递同样的参数时，所有重载方法的行为必须一致。 调用已有接口重载方法，应该了解清楚方法的行为是否是自己期望的，否则不要调用。

53. 慎用可变参数

       可变参数方法称作variable arity method。在定义参数数目不定的方法时，可变参数是一种很方便的方式。在使用可变参数之前，要先包含所有必要的参数，并且要关注使用可变参数所带来的性能影响(因为每次调用可变参数方法都会导致一次数组分配和初始化)。

54. 返回零长度的数组或者集合，而不是null

     返回null会使API更难于使用，更容易出错，而且没有任何性能优势。万一有证据表明分配零长度的集合损害了程序的性能，可以通过重复返回同一个不可变的零长度集合，基本很难遇到。

55. 谨慎返回Optional

      Optional本质上与受检异常相类似，因为它们强迫API用户面对没有返回值的现实。

55.1 不适合Optional的情形

        a. 不要通过返回Optional的方法返回null，因为这违背了本意。

        b. 容器类型包括集合、映射、Stream、数组和Optional，都不应该被包装在Optional中。应该返回空的容器，使客户免于处理Optional。

        c. 不应该返回基本包装类型的Optional，“小型的基本类型”(Boolean、Byte、Character、Short、Float)除外，因为Optional有两级包装而不是0级。

        d. 不适合用Optional作为键、值，或者集合或数组中的元素，因为可能造成混乱和出错。

        e. 不适合注重性能的方法(最好返回null，或抛出异常)，因为Optional是一个必须进行分配和初始化的对象。

         f. 尽量不要将Optional用在返回值以外的任何其它用途。

55.2 适合optional的情形

        如果无法返回结果并且当没有返回结果时客户端必须执行特殊的处理，那么就应该声明该方法返回Optional<T>。

56. 为所有导出的API元素编写文档注释

      如果想使一个API真正可用，就必须为其编写文档，而文档注释是最好，最有效的途径。

56.1 为了正确地编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。对于那些没有导出的，也建议做文档注释，方便代码维护。

56.2 方法的文档注释应该简洁地描述出它和客户端之间的约定。

       a. 应该说明这个方法做了什么，而不是如何做的

       b. 应该列举方法所有前提条件和后置条件，还应该描述它的副作用

       c. 应该有一个@param标签，一个@return标签，以及描述每个抛出异常的@throws标签

       d. “this”用在实例方法注释中，应该始终指的是方法调用所在的对象

56.3 文档注释在源代码和产生的文档中都应该是易于阅读的。在注释内部允许HTML标签，但是HTML元字符必须要经过转义。

56.4 每个文档注释的第一句话应该是概要描述。同一个类或者接口中的两个成员或者构造器，不应该具有同样的概要描述。

56.5 当为范型或者方法编写文档时，确保要在文档中说明所有的类型参数。

56.6 当为枚举类型编写文档时，要确保在文档中说明常量，以及类型，和任何公有方法。

56.7 为注解类型编写文档时，要确保在文档中说明所有成员，以及类型本身。

56.8 类或者静态方法是否线程安全，应该在文档中对它的线程安全级别进行说明。

56.9 对于多个关联类组成的复杂API，有必要用一个外部文档来描述API的总体结构。

56.10 阅读由Javadoc工具生成的网页。