EffectiveJava--方法

本章内容：
1. 检查参数的有效性
2. 必要时进行保护性拷贝
3. 谨慎设计方法签名
4. 慎用重载
5. 慎用可变参数
6. 返回零长度的数组或者集合，而不是null
7. 为所有导出的API元素编写文档注释

1. 检查参数的有效性
    每当编写方法或者构造器的时候，应该考虑他的参数有哪些限制。应该把这些限制写到文档中，并且在这个方法体的开头处，通过显式的检查来实施这些限制。养成这样的习惯是非常重要的。
    对于公有的方法，要用Javadoc的@throws标签（tag）在文档中说明违反参数值限制会抛出异常。手工抛出异常，并且添加@throws注解说明原因 。如下：
    /**
     * hello.....
     * @param m
     * @return
     * @throws NullPointerException if m is null
     * @throws ArithmeticException if m is less than or equals to 0
     */
    public BigInteger mod(BigInteger m) {
        if(m == null){
            throw new NullPointerException("m is null:" + m);
        }
        if (m.signum() <= 0) {
            throw new ArithmeticException("Modulus <= 0: " + m);
        }
        // Do something
        return null;
    }
    非公有的方法通常应该使用断言（assertion）来检查他们的参数。如下：
    /**
     *
     * @param a
     * @param offset
     * @param length
     */
    private static void sort(long[] a,int offset,int length){
        assert a != null;
        assert offset >= 0 && offset <= a.length;
        System.out.println("sort do something");
    }
    注意以上不同于junit里的断言方法：
    private static void sort2(long[] a, int offset, int length) {
        Assert.assertTrue("a is null", a != null);
        Assert.assertTrue(offset >= 0 && offset <= a.length);
        System.out.println("sort do something");
    }
    断言如果失败，将会抛出AssertionError，如果它们没有起到作用，本质上不会有成本开销，除非通过将-ea(或者-enableassertions)标记传递给java解释器，来启动他们（一般来说 assert 在开发的时候是检查程序的安全性的，在发布的时候通常都不使用assert ）。

2. 必要时进行保护性拷贝
    使Java使用起来如此舒适的一个因素在于，它是一门安全的语言。这意味着，它对于缓冲区溢出、数组越界、非法指针以及其他的内存破坏错误都自动免疫。
    假设类的客户端会尽其所能来破坏这个类的约束条件，因此你必须保护性的设计程序。 如下代码：
        import java.util.Date;
        public final class Period {
            private final Date start;
            private final Date end;
            public Period(Date start,Date end) {
                if(start.compareTo(end) > 0){
                    throw new IllegalArgumentException(start + " after " + end);
                }
                this.start = start;
                this.end = end;
            }
        
            public Date start(){
                return start;
            }
        
            public Date end(){
                return end;
            }
            //remainder omitted
        }
   这个类看上去没有什么问题，时间是不可改变的。然而Date类本身是可变的，因此很容易违反这个约束条件：
        Date start = new Date();
        Date end = new Date();
        Period period = new Period(start, end);
        end.setYear(78); // 修改值
        System.out.println(period.end());
   为了保护Period实例的内部信息避免受到修改，对于构造器的每个可变参数进行保护性拷贝（defensive copy）是必要的，并且使用备份对象作为Period实例的组件，而不使用原始的对象：
        public Period(Date start,Date end) {
            this.start = new Date(start.getTime());
            this.end = new Date(end.getTime());
            if(this.start.compareTo(this.end) > 0){
                throw new IllegalArgumentException(this.start + " after " + this.end);
            }
        }
   用了新的构造器之后，上述的攻击对于Period实例不再有效。注意，保护性拷贝是在检查参数的有效性之前进行的，并且有效性检查是针对拷贝之后的对象，而不是原始对象。 这样做可以避免在危险阶段期间从另一个线程改变类的参数。
   对于参数类型可以被不可信任方子类化的参数，请不要使用clone方法进行保护性拷贝。
    虽然替换构造器就可以成功地避免上述的攻击，但是改变Period实例仍然是有可能的，因为它的访问方法提供了对其可变内部成员的访问能力，为了防止这种攻击，可以让访问方法返回拷贝对象：
        public Date start(){
            return new Date(start.getTime());
        } 
        public Date end(){
            return new Date(end.getTime());
        }
    参数的保护性拷贝不仅仅针对不可变类。每当编写编写方法和构造器时，如果他要允许客户提供的对象进入到内部数据结构中，则有必要考虑一下，客户提供的对象是否有可能是可变的，我是否能够容忍这种可变性。特别是你用到list、map之类连接元素时。 如果答案是否定的，就必须对该对象进行保护性拷贝，并且让拷贝之后的对象而不是原始对象进入到数据结构中。
   在内部组件返回给客户端的时候，也要考虑是否可以返回一个指向内部引用的数据，解决文字是应该返回保护性拷贝。或者，不使用拷贝，你也可以返回一个不可变对象。
    可以肯定的说，上述的真正启示在于，只要有可能，都应该使用不可变的对象作为对象内部的组件（注意是不可变对象），这样就不必再为保护性拷贝操心。保护性拷贝可能会带来相关的性能损失，但不一定是。如果类具有从客户端得到或者返回到客户端的可变组件，类就必须保护性的拷贝这些组件。如果拷贝的成本受到限制，并且类信任他的客户端不会进行修改，或者恰当的修改，那么就需要在文档中指明客户端调用者的责任（不的修改或者如何有效修改）。
    特别是当你的可变组件的生命周期很长，或者会多层传递时，隐藏的问题往往暴漏出来就很可怕。

3. 谨慎设计方法签名
（1）谨慎地选择方法的名称
（2）不要过于追求提供便利的方法
（3）避免过长的参数列表，目标是四个参数或者更少，如果多于四个了就该考虑重构这个方法了（分解方法、创建辅助类、从对象构建到方法调用都采用Builder模式）。
（4）对于参数类型、要优先使用接口而不是类。如果使用的是类而不是接口，则限制了客户端只能传入特定的实现，如果碰巧输入的数据是以其他的形式存在，就会导致不必要的、可能非常昂贵的拷贝操作。
（5）对语言boolean参数，优先使用两个元素的枚举类型。

4. 慎用重载
    下面的例子根据一个集合是Set、List还是其他的集合类型，来对它进行分类：
        public class CollectionClassfier {
            public static String classify(Set<?> s) {
                return "Set";
            }
            public static String classify(List<?> l) {
                return "List";
            }
            public static String classify(Collection<?> c) {
                return "Unknown collection";
            }
            public static void main(String[] args) {
                Collection<?>[] collections = {new HashSet<String>(), new ArrayList<BigInteger>(), new HashMap<String,String>().values()};
                for (Collection<?> c : collections)
                    System.out.println(classify(c));
            }
        }
    这里你可能会期望程序打印出Set、List、Unknown Collection，然而实际上却不是这样，输出的结果是3 个"Unknown Collection"。因为classify方法被重载了，需要调用哪个函数是在编译期决定的，for中的三次迭代参数的编译类型是相同的：Collection<?>。对于重载方法的选择是静态的，而对于被覆盖的方法的选择则是动态的。选择被覆盖的方法的正确版本是在运行时进行的，选择的依据是被调用的方法所在对象的运行时类型。这里重新说明一下，当一个子类包含的方法声明与其祖先类中的方法声明具有同样的的签名时，方法就被覆盖了。如果实例方法在子类中被覆盖了，并且这个方法是在该子类的实例上被调用的，那么子类中的覆盖方法将会执行，而不管该子类实例的编译时类型到底是什么。
        class Wine{
            String name() {return "wine"; }
        }
        class SparklingWine extends Wine{
            @Override String name(){return "sparkling wine"; }
        }
        class Champagne extends Wine{
            @Override String name(){return "Champagne"; }
        }
        public class Overriding{
            public static void main(String[] args){
                Wine[] = {new Wine(), new SparklingWine(), new Champagne() };
            }
            for(Wine wine : wines){
                System.out.println(wine.name());
            }
        }
    正如你所预期的那样，这个程序打印出“wine, sparkling wine, champagne”，当调用被覆盖的方法时，对象的编译时类型不会影响到哪个方法将被执行。最为具体的那个覆盖版本总是会得到执行。

    对于开始的集合输出类的最佳修正方案是，用单个方法来替换这三个重载的classity方法，如下：
        public static String classify(Collection<?> c) {
            return c instanceof Set ? "Set" : c instanceof List ? "List" : "Unknown Collection";
        }
   
    因此，应该避免胡乱地使用重载机制。
    一、安全而保守的策略是，永远不要导出两个具有相同参数数目的重载方法。比如两个重载函数均有一个参数，其中一个是整型，另一个是Collection<?>，对于这种情况，int 和Collection<?>之间没有任何关联，也无法在两者之间做任何的类型转换，否则将会抛出ClassCastException 的异常，因此对于这种函数重载，我们是可以准确确定的。反之，如果两个参数分别是int 和short，他们之间的差异就不是这么明显。
    二、如果方法使用可变参数，保守的策略是根本不要重载它。
    三、对于构造器，你没有选择使用不同名称的机会，一个类的多个构造器总是重载的，但是构造器也不可能被覆盖。
    四、在Java 1.5 之后，需要对自动装箱机制保持警惕。演示如下：
        public class SetList {
            public static void main(String[] args) {
                Set<Integer> s = new TreeSet<Integer>();
                List<Integer> l = new ArrayList<Integer>();
                for (int i = -3; i < 3; ++i) {
                    s.add(i);
                    l.add(i);
                }
                for (int i = 0; i < 3; ++i) {
                    s.remove(i);
                    l.remove(i);
                }
                System.out.println(s + " " + l);
            }
        }
    在执行该段代码前，我们期望的结果是Set 和List 集合中大于等于的元素均被移除出容器，然而在执行后却发现事实并非如此，其结果为：[-3,-2,-1] [-2,0,2]。这个结果和我们的期望还是有很大差异的，为什么Set 中的元素是正确的，而List 则不是，是什么导致了这一结果的发生呢？下面给出具体的解释：
        s.remove(i)调用的是Set 中的remove(E)，这里的E 表示Integer，Java 的编译器会将i 自动装箱到Integer 中，因此我们得到了想要的结果。
        l.remove(i)实际调用的是List 中的remove(int index)重载方法，而该方法的行为是删除集合中指定索引的元素。这里分别对应第0 个，第1 个和第2 个。
    为了解决这个问题，我们需要让List 明确的知道，我们需要调用的是remove(E)重载函数，而不是其他的，这样我们就需要对原有代码进行如下的修改：
        public class SetList {
            public static void main(String[] args) {
                Set<Integer> s = new TreeSet<Integer>();
                List<Integer> l = new ArrayList<Integer>();
                for (int i = -3; i < 3; ++i) {
                    s.add(i);
                    l.add(i);
                }
                for (int i = 0; i < 3; ++i) {
                    s.remove(i);
                    l.remove((Integer)i); //or remove(Integer.valueOf(i));
                }
                System.out.println(s + " " + l);
            }
        }
    总结，对于多个具有相同参数数目的方法来说，应该尽量避免重载方法。我们应当保证：当传递同样的参数时，所有重载方法的行为必须一致。

5. 慎用可变参数
    Java1.5发行版本中增加了可变参数方法，可变参数方法接受0个或者多个指定类型的参数。可变参数机制通过先创建一个数组，数组的大小为在调用位置所传递的参数数量，然后将参数值传到数组中，最后将数组传递给方法，如下：
        static int sum(int... args) {
            int sum = 0;
            for (int arg : args)
                sum += arg;
            retrun sum;
        }
    上面的方法可以正常的工作，但是在有的时候，我们可能需要至少一个或者多个某种类型参数的方法，如下：
        static int min(int...args) {
            if (args.length == 0)
                throw new IllegalArgumentException("Too few arguments.");
            int min = args[0];
            for (int i = 0; i < args.length; ++i) {
                if (args[i] < min)
                    min = args[i];
                }
            return min;
        }
    对于上面的代码主要存在两个问题，一是如果调用者没有传递参数是，该函数将会在运行时抛出异常，而不是在编译期报错。另一个问题是这样的写法也是非常不美观的，函数内部必须做参数的数量验证，不仅如此，这也影响了效率。将编译期可以完成的事情推到了运行期。下面提供了一种较好的修改方式，如下：
        static int min(int firstArg,int...remainingArgs) {
            int min = firstArgs;
            for (int arg : remainingArgs) {
                if (arg < min)
                    min = arg;
                }
            return min;
        }
    由此可见，当你真正需要让一个方法带有不定数量的参数时，可变参数就非常有效。

    有的时候在重视性能的情况下，使用可变参数机制要特别小心。可变参数方法的每次调用都会导致进行一次数组分配和初始化。如果确定确实无法承受这一成本，但又需要可变参数的灵活性，还有一种模式可以弥补这一不足。假设确定对某个方法95%的调用会有3 个或者更少的参数，就声明该方法的5 个重载，每个重载方法带有0 个至3 个普通参数，当参数的数目超过3 个时，就使用一个可变参数方法：
        public void foo() {}
        public void foo(int a1) {}
        public void foo(int a1,int a2) {}
        public void foo(int a1,int a2,int a3) {}
        public void foo(int a1,int a2,int a3,int...rest) {}
    所有调用中只有5%参数数量超过3 个的调用需要创建数组。就像大多数的性能优化一样，这种方法通常不恰当，但是一旦真正需要它时，还是非常有用处的。

    简而言之，在定义参数数目不定的方法时，可变参数方法是一种很方便的方式，但是它们不应该过度滥用。如果使用不当，会产生混乱的结果。

6. 返回零长度的数组或者集合，而不是null
    请看如下代码：
        public class CheesesShop {
            private final List<Cheese> cheesesInStock = new List<Cheese>();
            public Cheese[] getCheeses() {
                if (cheesesInStock.size() == 0)
                    return null;
                return cheeseInStock.toArray(null);
            }
        }
    从以上代码可以看出，当没有Cheese 的时候，getCheeses()函数返回一种特例情况null。这样做的结果会使所有的调用代码在使用前均需对返回值数组做null 的判断，如下：
        public void testGetCheeses(CheesesShop shop) {
            Cheese[] cheeses = shop.getCheeses();
            if (cheese !=null && Array.asList(cheeses).contains(Cheese.STILTON))
                System.out.println("Jolly good, just the thing.");
            }
    对于一个返回null 而不是零长度数组或者集合的方法，几乎每次用到该方法时都需要这种曲折的处理方式。很显然，这样是比较容易出错的，因为编写客户端程序的程序员可能会忘记写这种专门的代码来处理null返回值。如果我们使getCheeses()函数在没有Cheese 的时候不再返回null，而是返回一个零长度的数组，那么我的调用代码将会变得更加简洁，如下：
        public void testGetCheeses2(CheesesShop shop) {
            if (Array.asList(shop.getCheeses()).contains(Cheese.STILTON))
                System.out.println("Jolly good, just the thing.");
        }

    有时候会有人认为：null返回值比零长度数据更好，因为它避免了分配数组所需要的开销。这种观点是站不住脚的，原因有两点。第一，在这个级别上担心性能问题是不明智的，除非分析表明这个方法正是造成性能问题的真正源头。第二，对于不返回任何元素的调用，每次都返回同一个零长度数组是有可能的，因为零长度数组是不可变的，而不可变对象有可能被自由地共享。
    相比于数组，集合亦是如此。

7. 为所有导出的API元素编写文档注释
    Java语言环境提供了一种被称为Javadoc的实用工具，从而使这项任务变得很容易。Javadoc利用特殊格式的文档注释，根据源代码自动产生API文档。
    为了正确地编写API文档，必须在每个被导出的类、接口、构造器、方法和域声明之前增加一个文档注释。如果类是可序列化的，也应该对它的序列化编写文档。

    方法的文档注释, 应该简洁地描述出它和客户端之间的约定, 这个约定说明这个方法做了什么, 而不是说明他是如何完成这项工作的。文档注释应该列举出这个方法的所有前置条件和后置条件，前提条件是客户端调用这个方法必须要满足的条件，后置条件是指调用成功之后，哪些条件必须要满足。一般情况下，前提条件是由@throws标签针对示受检的异常所隐含描述的，每个未受检的异常都对应一个前提违例，当然也可以在@param标记中指定前提条件。除了前提条件和后置条件，还需要描述它们的副作用, 如果有的话。最后，文档注释也应该描述类或者方法的线程安全性。
   为了完整地描述方法的约定，方法的文档注释应该让每个参数都有一个@param标签，以及一个@return标签（除非为void），以及对于该方法抛出的每个异常，无论是受检还是未受检的，都有一个@throws标签。
    跟在@param标签和@return标签后面的文字应该是一个名词短语，描述了这个参数或者返回值所表示的值。跟在@throws之后的文字应该包含单词"if" 紧接着是一个名词短语, 描述了这个异常将在什么情况下抛出。有时候也会用算术表达式来代替名词短语。按惯例，@param、@return或者@throws标签后面的短语或者句子都不用句点来结束。如下：
        /**
          * 概要描述
          *
          * 详细说明
          *
          * @param xxx
          * @return xxx
          * @throws xxx
          *                 ({@code index < 0 || index >= this.size()})
          */
        E get(int index);
    Javadoc工具会把文档注释翻译成HTML，文档注释中包含的任意HTML元素都会出现在结果HTML中，但是HTML元字符必须要经过转义。使用javadoc中的{@code}标签来代替html中的<code>标签以代码字体呈现。还有一种方法是用{@literal xxx}标签将xxx包围起来，除了它不以代码字体渲染文本之外，其余方面就像{@code}标签一样。

    每个文档注释的第一句话成了该注释所属元素的概要描述，不一个类或者接口中的两个成员或者构造器不应该具有同样的概要描述。对类或接口而言概要描述应该是一个名词短语，对于方法和构造器而言, 概要描述应该是一个完整的动词短语, 描述了该方法所执行的动作
    概要描述中的句点会过早的终止这个描述，最好的解决办法是将句点或其他东西用{@literal}包起来，
   
    还应该在文档中对类中否是线程安全的，是否可序列化的进行说明。
    虽然为所有导出的API元素提供文档注释是必要的，但是这样做并非永远就足够了。对于由多个关联的类组成的复杂API，通常有必要用一个外部文档来描述该API的总体结构，对文档注释进行补充。如果有这样的文档，相关的类或者包文档注释就应该包含一个对这个外部文档的链接。