阿里Java开发手冊之编程规约

对于程序猿来说，编程规范能够养成良好的编程习惯，提高代码质量，减少沟通成本。就在2月9号，阿里出了一份Java开发手冊(正式版)，分为编程规约。异常日志。MySQL规约，project规约。安全规约五个章节。

这里我依据阿里的编程规约，重点记录（黑色加粗部分）自己还未做好的一些规范，同一时候方便查阅。

编程规约

一、命名规约

• 【强制】代码中的命名均不能下面划线或美元符号開始。也不能下面划线或美元符号结束。

  反例： _name / __name / $Object / name_ / name$ / Object$ 
  1
  1

• 【强制】 代码中的命名严禁使用拼音与英文混合的方式。更不同意直接使用中文的方式。 说明：正确的英文拼写和语法能够让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式 也要避免採用。

  反例： DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3 
  
  正例： alibaba / taobao / youku / hangzhou 等国际通用的名称。可视同英文。
  1
  2
  3
  1
  2
  3

• 【强制】类名使用 UpperCamelCase 风格。必须遵从驼峰形式。但下面情形例外：（领域模型 的相关命名）DO / BO / DTO / VO 等

  正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion 
  
  反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion 
  1
  2
  3
  1
  2
  3

• 【强制】方法名、參数名、成员变量、局部变量都统一使用 lowerCamelCase 风格。必须遵从 驼峰形式

  正例： localValue / getHttpMessage() / inputUserId
  1
  1

• 【强制】常量命名所有大写。单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长

  正例： MAX_STOCK_COUNT 
  
  反例： MAX_COUNT 
  1
  2
  3
  1
  2
  3

• 【强制】抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾。測试类 命名以它要測试的类的名称開始，以 Test 结尾

• 【强制】中括号是数组类型的一部分，数组定义例如以下：String[] args

  反例：请勿使用 String args[]的方式来定义。 
  1
  1

• 【强制】POJO 类中布尔类型的变量，都不要加 is。否则部分框架解析会引起序列化错误

  反例：定义为基本数据类型 boolean isSuccess。的属性。它的方法也是 isSuccess()。RPC 框架在反向解析的时候。“以为”相应的属性名称是 success。导致属性获取不到。进而抛出异 常。 
  1
  1

• 【强制】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用 单数形式。可是类名假设有复数含义，类名能够使用复数形式

  正例： 应用工具类包名为 com.alibaba.open.util、类名为 MessageUtils（此规则參考 spring 的框架结构） 
  1
  1

• 【强制】杜绝全然不规范的缩写，避免望文不知义

  反例： AbstractClass“缩写”命名成 AbsClass。condition“缩写”命名成 condi，此类 任意缩写严重减少了代码的可阅读性。
   
  1
  1

• 【推荐】假设使用到了设计模式，建议在类名体现出详细的设计模式

  说明：将设计模式体如今名字中，有利于阅读者高速理解架构设计思想。
   
  
  正例：public class OrderFactory;    
  public class LoginProxy;     
  public class ResourceObserver; 
  1
  2
  3
  4
  5
  1
  2
  3
  4
  5

• 【推荐】接口类中的方法和属性不要加不论什么修饰符号（public 也不要加），保持代码的简洁 性，并加上有效的 Javadoc 凝视。尽量不要在接口里定义变量。假设一定要定义变量。肯定是与接口方法相关，而且是整个应用的基础常量

  正例：接口方法签名：void f(); 
  接口基础常量表示：String COMPANY = "alibaba"; 
  
  反例：接口方法定义：public abstract void f();
  
  说明：JDK8 中接口同意有默认实现。那么这个 default 方法，是对全部实现类都有价值的默 认实现。 
  1
  2
  3
  4
  5
  6
  1
  2
  3
  4
  5
  6

• 接口和实现类的命名有两套规则：

  • 【强制】对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部 的实现类用 Impl 的后缀与接口差别

  正例：CacheServiceImpl 实现 CacheService 接口
  1
  1

  • 【推荐】假设是形容能力的接口名称。取相应的形容词做接口名（一般是–able 的形式）

  正例：AbstractTranslator 实现 Translatable
  1
  1

• 【參考】枚举类名建议带上Enum后缀，枚举成员名称须要全大写，单词间用下划线隔开

  说明：枚举事实上就是特殊的常量类。且构造方法被默认强制是私有。
  
  
  正例：枚举名字：DealStatusEnum，成员名称：SUCCESS / UNKOWN_REASON
  1
  2
  3
  1
  2
  3

• 【參考】各层命名规约

  • Service/DAO 层方法命名规约

    • 获取单个对象的方法用 get 做前缀
    • 获取多个对象的方法用 list 做前缀
    • 获取统计值的方法用 count 做前缀
    • 插入的方法用 save（推荐）或 insert 做前缀
    • 删除的方法用 remove（推荐）或 delete 做前缀
    • 改动的方法用 update 做前缀

  • 领域模型命名规约

    • 数据对象：xxxDO，xxx 即为数据表名
    • 传输数据对象：xxxDTO。xxx 为业务领域相关的名称
    • 展示对象：xxxVO。xxx 一般为网页名称。
    • POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO

二、常量定义

• 【强制】不同意出现不论什么魔法值（即未经定义的常量）直接出如今代码中。

   反例： String key="Id#taobao_"+tradeId；         cache.put(key, value); 
  1
  1

• 【强制】long 或者 Long 初始赋值时，必须使用大写的 L。不能是小写的 l，小写easy跟数字 1 混淆。造成误解。

  说明：Long a = 2l; 写的是数字的 21，还是 Long 型的 2? 
  1
  1

• 【推荐】不要使用一个常量类维护全部常量，应该按常量功能进行归类，分开维护。

  如：缓存 相关的常量放在类：CacheConsts 下。系统配置相关的常量放在类：ConfigConsts 下。 说明：大而全的常量类，非得使用查找功能才干定位到改动的常量，不利于理解和维护

• 【推荐】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子project内共享常量、包 内共享常量、类内共享常量

  • 跨应用共享常量：放置在二方库中。一般是 client.jar 中的 constant 文件夹下

  • 应用内共享常量：放置在一方库的 modules 中的 constant 文件夹下

  • 子project内部共享常量：即在当前子project的 constant 文件夹下

  • 包内共享常量：即在当前包下单独的 constant 文件夹下

  • 类内共享常量：直接在类内部 private static final 定义

• 【推荐】假设变量值仅在一个范围内变化用 Enum 类。假设还带有名称之外的延伸属性，必须 使用 Enum 类，以下正例中的数字就是延伸信息。表示星期几

  正例：public Enum{ MONDAY(1), TUESDAY(2), WEDNESDAY(3), THURSDAY(4), FRIDAY(5), SATURDAY(6), SUNDAY(7);} 
  1
  1

三、格式规约

• 【强制】大括号的使用约定。

  假设是大括号内为空，则简洁地写成{}就可以，不须要换行；假设 是非空代码块则：

  • 左大括号前不换行。
  • 左大括号后换行。

  • 右大括号前换行。

  • 右大括号后还有 else 等代码则不换行；表示终止右大括号后必须换行。

• 【强制】 左括号和后一个字符之间不出现空格。相同，右括号和前一个字符之间也不出现空格。

• 【强制】if/for/while/switch/do 等保留字与左右括号之间都必须加空格。

• 【强制】不论什么运算符左右必须加一个空格。

  说明：运算符包含赋值运算符=、逻辑运算符&&、加减乘除符号、三目执行符等
  1
  1

• 【强制】缩进採用 4 个空格，禁止使用 tab 字符

  说明：假设使用 tab 缩进。必须设置 1 个 tab 为 4 个空格。
  IDEA 设置 tab 为 4 个空格时， 请勿勾选 Use tab character；而在 eclipse 中。必须勾选 insert spaces for tabs
  1
  1

• 【强制】单行字符数限制不超过 120 个，超出须要换行，换行时遵循例如以下原则：

  • 第二行相对第一行缩进 4 个空格。从第三行開始，不再继续缩进，參考演示样例。

  • 运算符与下文一起换行。

  • 方法调用的点符号与下文一起换行

  • 在多个參数超长。逗号后进行换行

  • 在括号前不要换行，见反例

  正例： 
      StringBuffer sb = new StringBuffer(); 
      //超过 120 个字符的情况下，换行缩进 4 个空格，而且方法前的点符号一起换行 
      sb.append("zi").append("xin")...   
      .append("huang")...  .append("huang")... 
      .append("huang");  
  
  
  反例： StringBuffer sb = new StringBuffer();
  //超过 120 个字符的情况下，不要在括号前换行 
  sb.append("zi").append("xin")...append    
  ("huang");   
  
  //參数非常多的方法调用可能超过 120 个字符，不要在逗号前换行  
  method(args1, args2, args3, ...      , argsX);  
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15

• 【强制】IDE 的 text file encoding 设置为 UTF-8; IDE 中文件的换行符使用 Unix 格式。 不要使用 windows 格式

• 【推荐】没有必要添加若干空格来使某一行的字符与上一行的对应字符对齐。

  正例： 
  int a = 3;  
  long b = 4L;  
  float c = 5F;  
  StringBuffer sb = new StringBuffer(); 
  
  说明：添加 sb 这个变量。假设须要对齐，则给 a、b、c 都要添加几个空格，在变量比較多的 情况下，是一种累赘的事情。 
  1
  2
  3
  4
  5
  6
  7
  1
  2
  3
  4
  5
  6
  7

• 【推荐】方法体内的运行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义 之间插入一个空行。同样业务逻辑和语义之间不须要插入空行。

四、OOP规约

• 【强制】避免通过一个类的对象引用訪问此类的静态变量或静态方法，无谓添加编译器解析成 本。直接用类名来訪问就可以。

• 【强制】全部的覆写方法，必须加@Override 注解。

  反例：getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的 0，加@Override 能够准确推断是否覆盖成功。另外，假设在抽象类中对方法签名进行改动，事实上现类会立即编 译报错。
   
  1
  1

• 【强制】同样參数类型，同样业务含义，才干够使用 Java 的可变參数，避免使用 Object

  说明：可变參数必须放置在參数列表的最后。（提倡同学们尽量不用可变參数编程） 
  
  正例：public User getUsers(String type, Integer... ids) 
  1
  2
  3
  1
  2
  3

• 【强制】对外暴露的接口签名。原则上不同意改动方法签名。避免对接口调用方产生影响。接 口过时必须加@Deprecated 注解。并清晰地说明採用的新接口或者新服务是什么

• 【强制】不能使用过时的类或方法

  说明：java.net.URLDecoder 中的方法 decode(String encodeStr) 这种方法已经过时，应 该使用双參数 decode(String source, String encode)。
  接口提供方既然明白是过时接口， 那么有义务同一时候提供新的接口。作为调用方来说，有义务去考证过时方法的新实现是什么。 
  1
  1

• 【强制】Object 的 equals 方法easy抛空指针异常，应使用常量或确定有值的对象来调用 equals。

  正例： "test".equals(object); 
  
  反例： object.equals("test"); 
  
  说明：推荐使用 java.util.Objects#equals （JDK7 引入的工具类） 
  1
  2
  3
  4
  5
  1
  2
  3
  4
  5

• 【强制】所有的同样类型的包装类对象之间值的比較。所有使用 equals 方法比較

  说明：对于 Integer var=?在-128 至 127 之间的赋值，Integer 对象是在 IntegerCache.cache 产生。会复用已有对象，这个区间内的 Integer 值能够直接使用==进行 推断，可是这个区间之外的全部数据，都会在堆上产生。并不会复用已有对象。这是一个大坑， 推荐使用 equals 方法进行推断
  1
  1

• 【强制】关于基本数据类型与包装数据类型的使用标准例如以下:

  • 全部的 POJO 类属性必须使用包装数据类型。

  • RPC 方法的返回值和參数必须使用包装数据类型。

  • 全部的局部变量【推荐】使用基本数据类型。

• 【强制】定义 DO/DTO/VO 等 POJO 类时，不要设定不论什么属性默认值

• 【强制】序列化类新增属性时。请不要改动 serialVersionUID 字段。避免反序列失败；如 果全然不兼容升级，避免反序列化混乱。那么请改动 serialVersionUID 值。

• 【强制】构造方法里面禁止增加不论什么业务逻辑。假设有初始化逻辑，请放在 init 方法中。

• 【强制】POJO 类必须写 toString 方法。使用 IDE 的中工具：source> generate toString 时，假设继承了还有一个 POJO 类，注意在前面加一下 super.toString。

• 【推荐】使用索引訪问用 String 的 split 方法得到的数组时。需做最后一个分隔符后有无 内容的检查。否则会有抛 IndexOutOfBoundsException 的风险。

• 【推荐】当一个类有多个构造方法，或者多个同名方法。这些方法应该按顺序放置在一起， 便于阅读。

• 【推荐】 类内方法定义顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter 方法。

• 【推荐】setter 方法中。參数名称与类成员变量名称一致，this.成员名=參数名。在 getter/setter 方法中，尽量不要添加业务逻辑，添加排查问题的难度

  反例： 
  public Integer getData(){      
      if(true)  {  
          return data + 100; 
      } else  { 
          return data - 100; 
  
      }  
  }  
  1
  2
  3
  4
  5
  6
  7
  8
  9
  1
  2
  3
  4
  5
  6
  7
  8
  9

• 【推荐】循环体内。字符串的联接方式，使用 StringBuilder 的 append 方法进行扩展

  反例： 
      String str = "start";      
      for(int i=0; i<100; i++){          
          str = str + "hello";      
      }  
  
  说明：反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象，然后进行 append 操作，最后通过 toString 方法返回 String 对象，造成内存资源浪费。 
  1
  2
  3
  4
  5
  6
  7
  1
  2
  3
  4
  5
  6
  7

• 【推荐】final 可提高程序响应效率。声明成 final 的情况：

  • 不须要又一次赋值的变量，包含类属性、局部变量。

  • 对象參数前加final，表示不同意改动引用的指向
  • 类方法确定不同意被重写

• 【推荐】慎用 Object 的 clone 方法来拷贝对象。

  说明：对象的 clone 方法默认是浅拷贝。若想实现深拷贝须要重写 clone 方法实现属性对象 的拷贝。 
  1
  1

• 【推荐】类成员与方法訪问控制从严：

  • 假设不同意外部直接通过 new 来创建对象，那么构造方法必须是 private。

  • 工具类不同意有 public 或 default 构造方法

  • 类非 static 成员变量而且与子类共享。必须是 protected。

  • 类非 static 成员变量而且仅在本类使用，必须是 private

  • 类 static 成员变量假设仅在本类使用。必须是 private

  • 若是 static 成员变量。必须考虑是否为 final

  • 类成员方法仅仅供类内部调用，必须是 private

  • 类成员方法仅仅对继承类公开，那么限制为 protected

    说明：不论什么类、方法、參数、变量。严控訪问范围。过宽泛的訪问范围。不利于模块解耦
    1
    1

五、集合处理

• 【强制】关于 hashCode 和 equals 的处理。遵循例如以下规则:

  • 仅仅要重写 equals，就必须重写 hashCode
  • 由于 Set 存储的是不反复的对象，根据 hashCode 和 equals 进行推断，所以 Set 存储的 对象必须重写这两个方法。
  • 假设自己定义对象做为 Map 的键。那么必须重写 hashCode 和 equals

• 【强制】 ArrayList的subList结果不可强转成ArrayList，否则会抛出ClassCastException 异常：java.util.RandomAccessSubList cannot be cast to java.util.ArrayList

  说明：subList 返回的是 ArrayList 的内部类 SubList。并非 ArrayList ，而是 ArrayList 的一个视图，对于 SubList 子列表的全部操作终于会反映到原列表上。
   
  1
  1

• 【强制】 在 subList 场景中，高度注意对原集合元素个数的改动，会导致子列表的遍历、增 加、删除均产生 ConcurrentModificationException 异常。

• 【强制】使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型全然 一样的数组。大小就是 list.size()。

反例：直接使用 toArray 无參方法存在问题，此方法返回值仅仅能是 Object[]类，若强转其他 类型数组将出现 ClassCastException 错误。 

正例：
    List<String> list = new ArrayList<String>(2);
    list.add("guan");      
    list.add("bao");       
    String[] array = new String[list.size()]; 
    array = list.toArray(array);  

说明：使用 toArray 带參方法，入參分配的数组空间不够大时，toArray 方法内部将又一次分配 内存空间。并返回新数组地址。假设数组元素大于实际所需。下标为[ list.size() ]的数组 元素将被置为 null，其他数组元素保持原值，因此最好将方法入參数组大小定义与集合元素个数一致
1
2
3
4
5
6
7
8
9
10
1
2
3
4
5
6
7
8
9
10

• 【强制】使用工具类 Arrays.asList()把数组转换成集合时，不能使用其改动集合相关的方 法，它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常

说明：asList 的返回对象是一个 Arrays 内部类。并没有实现集合的改动方法。Arrays.asList 体现的是适配器模式，仅仅是转换接口，后台的数据仍是数组。
 
1
1

• 【强制】泛型通配符

说明：苹果装箱后返回一个<?
 extends Fruits>对象。此对象就不能往里加不论什么水果，包含 苹果
1
1

• 【强制】不要在 foreach 循环里进行元素的 remove/add 操作。

  remove 元素请使用 Iterator 方式。假设并发操作，须要对 Iterator 对象加锁

• 【强制】 在 JDK7 版本号以上，Comparator 要满足自反性，传递性，对称性，不然 Arrays.sort， Collections.sort 会报 IllegalArgumentException 异常

• 【推荐】集合初始化时，尽量指定集合初始值大小

  说明：ArrayList 尽量使用 ArrayList(int initialCapacity) 初始化。 
  1
  1

• 【推荐】使用 entrySet 遍历 Map 类集合 KV。而不是 keySet 方式进行遍历

  说明：keySet 事实上是遍历了 2 次，一次是转为 Iterator 对象，还有一次是从 hashMap 中取出 key 所相应的 value。而 entrySet 仅仅是遍历了一次就把 key 和 value 都放到了 entry 中。效 率更高。
  假设是 JDK8，使用 Map.foreach 方法
  1
  1

• 【推荐】高度注意 Map 类集合 K/V 能不能存储 null 值的情况，例如以下表格：

  

  反例： 因为 HashMap 的干扰，非常多人觉得 ConcurrentHashMap 是能够置入 null 值。注意存储 null 值时会抛出 NPE 异常
  1
  1

• 【參考】合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和 不稳定性(unorder)带来的负面影响。
• 【參考】利用 Set 元素唯一的特性，能够高速对一个集合进行去重操作。避免使用 List 的 contains 方法进行遍历、对照、去重操作

六、并发处理

• 【强制】获取单例对象须要保证线程安全，当中的方法也要保证线程安全

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

  正例： 
  public class TimerTaskThread extends Thread { 
      public TimerTaskThread(){     
          super.setName("TimerTaskThread");  
          ...
      }
  }  
  1
  2
  3
  4
  5
  6
  7
  1
  2
  3
  4
  5
  6
  7

• 【强制】线程资源必须通过线程池提供。不同意在应用中自行显式创建线程。

  说明：使用线程池的优点是降低在创建和销毁线程上所花的时间以及系统资源的开销。解决资源不足的问题。假设不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者 “过度切换”的问题。
  1
  1

• 【强制】线程池不同意使用 Executors 去创建。而是通过 ThreadPoolExecutor 的方式，这样 的处理方式让写的同学更加明白线程池的执行规则，规避资源耗尽的风险

  说明：Executors 返回的线程池对象的弊端例如以下： 
  
  1、FixedThreadPool 和 SingleThreadPool:  
      同意的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。
   
  
  2、CachedThreadPool 和 ScheduledThreadPool:  
      同意的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程。从而导致 OOM
  1
  2
  3
  4
  5
  6
  7
  1
  2
  3
  4
  5
  6
  7

• 【强制】SimpleDateFormat 是线程不安全的类。一般不要定义为 static 变量，假设定义为 static，必须加锁。或者使用 DateUtils 工具类

  说明：假设是 JDK8 的应用，能够使用 Instant 取代 Date，LocalDateTime 取代 Calendar， DateTimeFormatter取代Simpledateformatter，官方给出的解释：simple beautiful strong immutable thread-safe
  1
  1

• 【强制】高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能 锁区块。就不要锁整个方法体。能用对象锁，就不要用类锁。

• 【强制】对多个资源、数据库表、对象同一时候加锁时，须要保持一致的加锁顺序，否则可能会造 成死锁

• 【强制】并发改动同一记录时。避免更新丢失。要么在应用层加锁，要么在缓存加锁，要么在 数据库层使用乐观锁。使用 version 作为更新根据

  说明：假设每次訪问冲突概率小于 20%，推荐使用乐观锁。否则使用悲观锁。
  乐观锁的重试次 数不得小于 3 次。 
  1
  1

• 【强制】多线程并行处理定时任务时，Timer 执行多个 TimeTask 时，仅仅要当中之中的一个没有捕获 抛出的异常，其他任务便会自己主动终止执行。使用 ScheduledExecutorService 则没有这个问题。

• 【推荐】使用 CountDownLatch 进行异步转同步操作，每一个线程退出前必须调用 countDown 方法，线程运行代码注意 catch 异常，确保 countDown 方法能够运行，避免主线程无法运行 至 countDown 方法，直到超时才返回结果。

• 【推荐】避免 Random 实例被多线程使用。尽管共享该实例是线程安全的。但会因竞争同一 seed 导致的性能下降。

  说明：Random 实例包含 java.util.Random 的实例或者 Math.random()实例。 
  
  正例：在 JDK7 之后，能够直接使用 API ThreadLocalRandom，在 JDK7 之前，能够做到每一个 线程一个实例。
   
  1
  2
  3
  1
  2
  3

• 【推荐】通过双重检查锁（double-checked locking）（在并发场景）实现延迟初始化的优 化问题隐患(可參考 The “Double-Checked Locking is Broken” Declaration),推荐问题 解决方式中较为简单一种（适用于 JDK5 及以上版本号），将目标属性声明为 volatile 型。

• 【參考】volatile 解决多线程内存不可见问题。

  对于一写多读。是能够解决变量同步问题。 可是假设多写，相同无法解决线程安全问题。假设是 count++操作。使用例如以下类实现

  AtomicInteger count = new AtomicInteger(); count.addAndGet(1); 
  假设是 JDK8，推 荐使用 LongAdder 对象，比 AtomicLong 性能更好（降低乐观锁的重试次数）。
   
  1
  2
  1
  2

• 【參考】 HashMap 在容量不够进行 resize 时因为高并发可能出现死链。导致 CPU 飙升，在 开发过程中注意规避此风险。

• 【參考】ThreadLocal 无法解决共享对象的更新问题，ThreadLocal 对象建议使用 static 修饰。这个变量是针对一个线程内全部操作共同拥有的，所以设置为静态变量。全部此类实例共享 此静态变量 ，也就是说在类第一次被使用时装载，仅仅分配一块存储空间，全部此类的对象(仅仅 要是这个线程内定义的)都能够操控这个变量。

七、控制语句

• 【强制】在一个 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 代码能够使用卫语句。或者状态模式来实现
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10

• 【推荐】除经常用法（如 getXxx/isXxx）等外。不要在条件推断中运行其他复杂的语句。将复 杂逻辑推断的结果赋值给一个有意义的布尔变量名。以提高可读性。

  说明：非常多 if 语句内的逻辑相当复杂，阅读者须要分析条件表达式的终于结果，才干明白什么 样的条件运行什么样的语句。那么，假设阅读者分析逻辑表达式错误呢？ 
  
  正例： //伪代码例如以下
  boolean existed = (file.open(fileName, "w") != null) && (...) || (...); 
  
  if (existed) { 
      ... 
  }  
  
  反例： 
  if ((file.open(fileName, "w") != null) && (...) || (...)) { 
      ... 
  } 
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13

• 【推荐】循环体中的语句要考量性能。下面操作尽量移至循环体外处理。如定义对象、变量、 获取数据库连接。进行不必要的 try-catch 操作（这个 try-catch 能否够移至循环体外）。

• 【推荐】接口入參保护，这样的场景常见的是用于做批量操作的接口。

• 【參考】方法中须要进行參数校验的场景：

  • 调用频次低的方法。

  • 运行时间开销非常大的方法，

  • 參数校验时间差点儿能够忽略不计。但假设由于參数错误导致

  • 中间运行回退。或者错误，那得不偿失。

  • 须要极高稳定性和可用性的方法。

  • 对外提供的开放接口。无论是 RPC/API/HTTP 接口

  • 敏感权限入口

• 【參考】方法中不须要參数校验的场景

  • 极有可能被循环调用的方法，不建议对參数进行校验。但在方法说明里必须注明外部參 数检查。

  • 底层的方法调用频度都比較高。一般不校验。

    毕竟是像纯净水过滤的最后一道，參数错 误不太可能究竟层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中，部署在同一 台server中，所以 DAO 的參数校验。能够省略。

  • 被声明成 private 仅仅会被自己代码所调用的方法，假设可以确定调用方法的代码传入參 数已经做过检查或者肯定不会有问题。此时可以不校验參数

八、凝视规约

• 【强制】类、类属性、类方法的凝视必须使用 Javadoc 规范，使用/* 内容 /格式，不得使用 //xxx 方式

  说明：在 IDE 编辑窗体中。Javadoc 方式会提示相关凝视。生成 Javadoc 能够正确输出对应注 释；在 IDE 中，project调用方法时。不进入方法就可以悬浮提示方法、參数、返回值的意义，提高 阅读效率
  1
  1

• 【强制】全部的抽象方法（包含接口中的方法）必需要用 Javadoc 凝视、除了返回值、參数、 异常说明外，还必须指出该方法做什么事情。实现什么功能。

  说明：对子类的实现要求，或者调用注意事项，请一并说明。 
  1
  1

• 【强制】全部的类都必须加入创建者信息。

• 【强制】方法内部单行凝视，在被凝视语句上方另起一行。使用//凝视。方法内部多行凝视 使用/* */凝视。注意与代码对齐。

• 【强制】全部的枚举类型字段必需要有凝视，说明每一个数据项的用途

• 【推荐】与其“半吊子”英文来凝视，不如用中文凝视把问题说清楚。专有名词与keyword保持 英文原文就可以。

  反例：“TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。
   
  1
  1

• 【推荐】代码改动的同一时候，凝视也要进行对应的改动。尤其是參数、返回值、异常、核心逻辑 等的改动。

  说明：代码与凝视更新不同步，就像路网与导航软件更新不同步一样，假设导航软件严重滞后， 就失去了导航的意义。
   
  1
  1

• 【參考】凝视掉的代码尽量要配合说明。而不是简单的凝视掉

  说明：代码被凝视掉有两种可能性：1）兴许会恢复此段代码逻辑。2）永久不用。前者假设没 有备注信息，难以知晓凝视动机。后者建议直接删掉（代码仓库保存了历史代码）。
   
  1
  1

• 【參考】对于凝视的要求：第一、可以准确反应设计思想和代码逻辑。第二、可以描写叙述业务含 义。使别的程序猿可以迅速了解到代码背后的信息。全然没有凝视的大段代码对于阅读者形同
  天书，凝视是给自己看的，即使隔非常长时间，也能清晰理解当时的思路；凝视也是给继任者看 的。使其可以高速接替自己的工作。

• 【參考】好的命名、代码结构是自解释的，凝视力求精简准确、表达到位。避免出现凝视的 一个极端：过多过滥的凝视，代码的逻辑一旦改动。改动凝视是相当大的负担。

• 【參考】特殊凝视标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描。 常常清理此类标记。

  线上故障有时候就是来源于这些标记处的代码。

  • 待办事宜（TODO）:（ 标记人，标记时间。[估计处理时间]） 表示须要实现，但眼下还未实现的功能。这实际上是一个 Javadoc 的标签。眼下的 Javadoc 还没有实现，但已经被广泛使用。仅仅能应用于类，接口和方法（由于它是一个 Javadoc 标签）。

  • 错误，不能工作（FIXME）:（标记人，标记时间，[估计处理时间]） 在凝视中用 FIXME 标记某代码是错误的，并且不能工作，须要及时纠正的情况

九、其它

• 【强制】在使用正則表達式时，利用好其预编译功能。能够有效加快正则匹配速度

  说明：不要在方法体内定义：Pattern pattern = Pattern.compile(规则); 
  1
  1

• 【强制】velocity 调用 POJO 类的属性时，建议直接使用属性名取值就可以，模板引擎会自己主动按 规范调用 POJO 的 getXxx()，假设是 boolean 基本数据类型变量（boolean 命名不须要加 is 前缀），会自己主动调用 isXxx()方法

  说明：注意假设是 Boolean 包装类对象。优先调用 getXxx()的方法
  1
  1

• 【强制】后台输送给页面的变量必须加$!{var}——中间的感叹号

  说明：假设 var=null 或者不存在。那么${var}会直接显示在页面上
  1
  1

• 【强制】注意 Math.random() 这种方法返回是 double 类型，注意取值的范围 0≤x<1（可以 取到零值，注意除零异常），假设想获取整数类型的随机数，不要将 x 放大 10 的若干倍然后 取整，直接使用 Random 对象的 nextInt 或者 nextLong 方法

• 【强制】获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime();
  
说明：假设想获取更加精确的纳秒级时间值。用 System.nanoTime()。在 JDK8 中，针对统计 时间等场景，推荐使用 Instant 类。


• 【推荐】尽量不要在 vm 中增加变量声明、逻辑运算符，更不要在 vm 模板中增加不论什么复杂的逻 辑。

• 【推荐】不论什么数据结构的构造或初始化。都应指定大小。避免数据结构无限增长吃光内存

• 【推荐】对于“明白停止使用的代码和配置”。如方法、变量、类、配置文件、动态配置属性 等要坚决从程序中清理出去，避免造成过多垃圾。