《阿里巴巴Java开发手册（终极版）》1-8之注释规约

编程规约 - 注释规约

【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用/*内容/格式，不得使用
// xxx 方式。
说明：在 IDE 编辑窗口中， Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注
释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高
阅读效率。
【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、
异常说明外，还必须指出该方法做什么事情，实现什么功能。
说明：对子类的实现要求，或者调用注意事项，请一并说明。
【强制】所有的类都必须添加创建者信息。

修改项：第 3 项

【强制】在一个 switch 块内，每个 case 要么通过 break / return 等来终止，要么注释说明程
序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default 语句并且
放在最后，即使它什么代码也没有。
【强制】在 if / else / for / while / do 语句中必须使用大括号，即使只有一行代码，避免使用
下面的形式： if (condition) statements;
【推荐】推荐尽量少用 else ， if - else 的方式可以改写成：
```
if(condition){
    ...
    return obj;
}
```
// 接着写 else 的业务逻辑代码;

说明：如果非得使用 if()…else if()…else… 方式表达逻辑，【强制】避免后续代码维
护困难，请勿超过 3 层。
正例：超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现，其中卫语句示例如下：
```
public void today() {
    if (isBusy()) {
        System.out.println(“change time.”);
        return;
    }
    if (isFree()) {
        System.out.println(“go to travel.”); 
        return;
    }
    System.out.println(“stay at home to learn Alibaba Java Coding Guidelines.”);
    return;
}
```

修改项：第 6 项

【强制】创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。
正例：

public class TimerTaskThread extends Thread {
public TimerTaskThread(){
    super.setName("TimerTaskThread"); ...
}

修改项：第 9 项

【强制】关于 hashCode 和 equals 的处理，遵循如下规则：
1）只要重写 equals ，就必须重写 hashCode 。
2）因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的
对象必须重写这两个方法。
3）如果自定义对象做为 Map 的键，那么必须重写 hashCode 和 equals 。
说明： String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象
作为 key 来使用。
【强制】 ArrayList 的 subList 结果不可强转成 ArrayList ，否则会抛出 ClassCastException
异常： java . util . RandomAccessSubList cannot be cast to java . util . ArrayList ;
说明： subList 返回的是 ArrayList 的内部类 SubList ，并不是 ArrayList ，而是
ArrayList 的一个视图，对于 SubList 子列表的所有操作最终会反映到原列表上。
【强制】在 subList 场景中，高度注意对原集合元素个数的修改，会导致子列表的遍历、增
加、删除均产生 ConcurrentModificationException 异常。

修改项：第 17 项、第 18 项

【强制】避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成
本，直接用类名来访问即可。
【强制】所有的覆写方法，必须加@ Override 注解。
反例： getObject() 与 get 0 bject() 的问题。一个是字母的 O ，一个是数字的 0，加@ Override
可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编
译报错。
【强制】相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object 。
说明：可变参数必须放置在参数列表的最后。（提倡同学们尽量不用可变参数编程）
正例：
```
public User getUsers(String type, Integer... ids)
```