android

Java 编码规范(精简版)

2018-07-20  本文已影响4人  AllenJJ

Java 编码规范(精简版)

[TOC]

import语句

即，不要出现类似这样的import语句：    import  java.util.*;

1.它有助于识别类名冲突：不同包中的两个类具有相同的名称。这可以用* import掩盖。
2.它使依赖显式化，以便任何需要稍后阅读代码的人都知道您要导入的内容以及您不想导入的内容。
3.它可以使编译速度更快，因为编译器不必搜索整个程序包来识别错误，尽管这对于现代编译器来说通常不是什么大问题。
4.使用现代IDE，显式导入的不便方面被最小化。大多数IDE允许您折叠导入部分，所以它不会妨碍，在需要时自动填充导入，并自动识别未使用的导入以帮助清理它们。

import com.acxiom.ams.common.exception.AMSInvalidInputException;
import com.acxiom.ams.model.front.PageQuery;
import com.acxiom.ams.model.front.ReceiveMessage;
import com.acxiom.ams.model.vo.UserMessageVo;
import com.acxiom.ams.msg.common.Exception.ServiceException;
import com.acxiom.ams.service.EmailService;
import com.acxiom.ams.service.MessageService;
import com.acxiom.ams.thread.AsyncService;

import org.springframework.beans.factory.annotation.Autowired;

import javax.validation.Valid;
import javax.validation.constraints.NotNull;

import java.util.List;

命名风格

反例：_name / __name / $name / name_ / name$ / name__

说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式
也要避免采用。
正例：alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。
反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3

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

正例： localValue / getHttpMessage() / inputUserId

正例：MAX_STOCK_COUNT
反例：MAX_COUNT

定义为基本数据类型 Boolean isDeleted 的属性，它的方法也是 isDeleted()，RPC
框架在反向解析的时候，“误以为”对应的属性名称是deleted，导致属性获取不到，进而抛出异常。

AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类随
意缩写严重降低了代码的可阅读性。

说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。
正例：   public class OrderFactory;
        public class LoginProxy;
        public class ResourceObserver;

正例：接口方法签名 void commit();
 接口基础常量 String COMPANY = "alibaba";
反例：接口方法定义 public abstract void f();
说明：JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默
认实现。


说明：枚举其实就是特殊的类，域成员均为常量，且构造方法被默认强制是私有。
正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON。

A) Service/DAO 层方法命名规约
1） 获取单个对象的方法用 get 做前缀。
2） 获取多个对象的方法用 list 做前缀，复数形式结尾如：listObjects。
3） 获取统计值的方法用 count 做前缀。
4） 插入的方法用 save/insert 做前缀。
5） 删除的方法用 remove/delete 做前缀。
6） 修改的方法用 update 做前缀。

常量定义

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

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

说明：大而全的常量类，杂乱无章，使用查找功能才能定位到修改的常量，不利于理解和维护。
正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 ConfigConsts 下。

1） 跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
2） 应用内共享常量：放置在一方库中，通常是子模块中的 constant 目录下。
反例：易懂变量也要统一定义成应用内共享常量，两位攻城师在两个类中分别定义了表示
“是”的变量：
类 A 中：public static final String YES = "yes";
类 B 中：public static final String YES = "y";
A.YES.equals(B.YES)，预期是 true，但实际返回为 false，导致线上问题。
3） 子工程内部共享常量：即在当前子工程的 constant 目录下。
4） 包内共享常量：即在当前包下单独的 constant 目录下。
5） 类内共享常量：直接在类内部 private static final 定义。

说明：如果存在名称之外的延伸属性应使用 enum 类型，下面正例中的数字就是延伸信息，表
示一年中的第几个季节。
正例：
public enum SeasonEnum {
 SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4);
 private int seq;
 SeasonEnum(int seq){
 this.seq = seq;
 }
}

代码格式

1） 左大括号前不换行。
2） 左大括号后换行。
3） 右大括号前换行。
4） 右大括号后还有 else 等代码则不换行；表示终止的右大括号后必须换行。

反例：if (空格 a == b 空格)

说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等

正例： 
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);  

正例：下例中实参的 args1，后边必须要有一个空格。 method(args1, args2, args3); 

说明：包括方法签名、结束右大括号、方法内代码、注释、空行、回车及任何不可见字符的总 行数不超过 80 行。 正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码 更加清晰；共性逻辑抽取成为共性方法，便于复用和维护。

OOP 规约

Foo aFoo = …;
Foo.aStaticMethod();//good
aFoo.aStaticMethod();//bad
somethingThatYieldsAFoo().aStaticMethod();//very bad

说明：getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的 0，加@Override 可以准确判断是否覆盖成功。
另外，如果在抽象类中对方法签名进行修改，其实现类会马上编 译报错。

说明：可变参数必须放置在参数列表的最后。（提倡同学们尽量不用可变参数编程） 
正例：public List<User> listUsers(String type, Long... ids) {...} 

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

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

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

说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或者入库检查，都由使用者来保证。 
正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。  
反例：比如显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调用 不成功时，返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线。所以包装 数据类型的 null 值，能够表示额外的信息，如：远程调用失败，异常退出。 

说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排 查问题。 

说明：框架在调用属性xxx的提取方法时，并不能确定哪个方法一定是被优先调用。

说明： 
    String str = "a,b,c,,"; 
    String[] ary = str.split(",");  
    // 预期大于 3，结果是 3 
    System.out.println(ary.length);

说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好；
保护方法虽然只是子类 关心，也可能是“模板设计模式”下的核心方法；
而私有方法外部一般不需要特别关心，是一个黑盒实现；
因为承载的信息价值较低，所有 Service 和 DAO 的 getter/setter方法放在类体最后。

反例： public Integer getData() {      
    if (condition) {  
        return this.data + 100; 
    } else { 
        return this.data - 100; 
    }  
} 

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

说明：对象的 clone 方法默认是浅拷贝，若想实现深拷贝需要重写 clone 方法实现域对象的 深度遍历式拷贝。 

说明：任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。 
思考：如果是一个 private 的方法，想删除就删除，可是一个 public 的 service 成员方法或
成员变量，删除一下，不得手心冒点汗吗？
变量像自己的小孩，尽量在自己的视线内，变量作 用域太大，无限制的到处跑，那么你会担心的。

集合处理

说明：String 重写了 hashCode 和 equals 方法，所以我们可以非常愉快地使用 String 对象作为 key 来使用。 

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

说明：使用 toArray 带参方法，入参分配的数组空间不够大时，toArray 方法内部将重新分配 内存空间，并返回新数组地址；
如果数组元素个数大于实际所需，下标为[ list.size() ] 的数组元素将被置为 null，其它数组元素保持原值，因此最好将方法入参数组大小定义与集 合元素个数一致。 
正例： 
    List<String> list = new ArrayList<String>(2);
    list.add("guan");      
    list.add("bao");       
    String[] array = new String[list.size()];      
    array = list.toArray(array);  
反例：直接使用 toArray 无参方法存在问题，此方法返回值只能是 Object[]类，若强转其它 类型数组将出现 ClassCastException 错误。 

说明：asList 的返回对象是一个 Arrays 内部类，并没有实现集合的修改方法。
Arrays.asList 体现的是适配器模式，只是转换接口，后台的数据仍是数组。 
    String[] str = new String[] { "you", "wu" };     
    List list = Arrays.asList(str); 
第一种情况：list.add("yangguanbao"); 运行时异常。 
第二种情况：str[0] = "gujin"; 那么 list.get(0)也会随之修改。 

说明：扩展说一下 PECS(Producer Extends Consumer Super)原则：
第一、频繁往外读取内 容的，适合用<? extends T>。
第二、经常往里插入的，适合用<? super T>。 

正例： 
    List<String> list = new ArrayList<>();      
    list.add("1");      
    list.add("2");    
    Iterator<String> iterator = list.iterator();  
    while (iterator.hasNext()) {              
        String item = iterator.next();                       
        if (删除元素的条件) {
        iterator.remove();                 
        }      
    } 
反例： 
    for (String item : list) {          
        if ("1".equals(item)) {              
            list.remove(item);          
        }     
    }  

说明：三个条件如下  
1） x，y 的比较结果和 y，x 的比较结果相反。  
2） x>y，y>z，则 x>z。  
3） x=y，则 x，z 比较结果和 y，z 比较结果相同。 
反例：下例中没有处理相等的情况，实际使用中可能会出现异常： 
    new Comparator<Student>() {           
        @Override          
        public int compare(Student o1, Student o2) {              
            return o1.getId() > o2.getId() ? 1 : -1;          
        }      
    };

说明：菱形泛型，即 diamond，直接使用<>来指代前边已经指定的类型。 
正例： 
    // <> diamond 方式 
    HashMap<String, String> userCache = new HashMap<>(16); 
    // 全省略方式 
    ArrayList<User> users = new ArrayList(10); 

说明：HashMap 使用 HashMap(int initialCapacity) 初始化。
正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即loader factor）默认为 0.75，如果暂时无法确定初始值大小，请设置为 16（即默认值）。 
反例：HashMap 需要放置 1024 个元素，由于没有设置容量初始大小，随着元素不断增加，容量 7 次被迫扩大，resize 需要重建 hash 表，严重影响性能。 

说明：keySet 其实是遍历了 2 次，一次是转为 Iterator 对象，另一次是从 hashMap 中取出 key 所对应的 value。而 entrySet 只是遍历了一次就把 key 和 value 都放到了 entry 中，效 率更高。如果是 JDK8，使用 Map.foreach 方法。 
正例：values()返回的是 V 值集合，是一个 list 集合对象；keySet()返回的是 K 值集合，是 一个 Set 集合对象；entrySet()返回的是 K-V 值组合集合。
集合类 Key Value Super 说明
Hashtable 不允许为null 不允许为null Dictionary 线程安全
ConcurrentHashMap 不允许为null 不允许为null AbstractMap 锁分段技术（JDBK：CAS）
TreeMap 不允许为null 允许为null AbstractMap 线程不安全
HashMap 允许为null 允许为null AbstractMap 线程不安全 
反例： 由于 HashMap 的干扰，很多人认为 ConcurrentHashMap 是可以置入 null 值，而事实上， 存储 null 值时会抛出 NPE 异常。 

说明：有序性是指遍历的结果是按某种比较规则依次排列的。稳定性指集合每次遍历的元素次序是一定的。
如：ArrayList 是 order/unsort；HashMap 是 unorder/unsort；TreeSet 是 order/sort。

并发处理

说明：资源驱动类、工具类、单例工厂类都需要注意。 

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

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

说明：Executors 返回的线程池对象的弊端如下： 
1）FixedThreadPool 和 SingleThreadPool:   
允许的请求队列长度为 Integer.MAX_VALUE，可能会堆积大量的请求，从而导致 OOM。 
2）CachedThreadPool 和 ScheduledThreadPool:   
允许的创建线程数量为 Integer.MAX_VALUE，可能会创建大量的线程，从而导致 OOM。 

正例：
注意线程安全，使用 DateUtils。亦推荐如下处理： 
private static final ThreadLocal<DateFormat> df = new ThreadLocal<DateFormat>() {        
    @Override        
    protected DateFormat initialValue() {            
        return new SimpleDateFormat("yyyy-MM-dd");        
    }    
};    
说明：如果是 JDK8 的应用，可以使用 Instant 代替 Date，LocalDateTime 代替 Calendar， DateTimeFormatter 代替 SimpleDateFormat，官方给出的解释：simple beautiful strong immutable thread-safe。 

说明：尽可能使加锁的代码块工作量尽可能的小，避免在锁代码块中调用 RPC 方法。 

说明：线程一需要对表 A、B、C 依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序 也必须是 A、B、C，否则可能出现死锁。

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

说明：注意，子线程抛出异常堆栈，不能在主线程 try-catch 到。 

说明：Random 实例包括 java.util.Random 的实例或者 Math.random()的方式。 
正例：在 JDK7 之后，可以直接使用 API ThreadLocalRandom，而在 JDK7 之前，需要编码保 证每个线程持有一个实例。 

反例： 
class LazyInitDemo {   
    private Helper helper = null;  
    public Helper getHelper() {  
        if (helper == null) synchronized(this) {      
            if (helper == null)         
            helper = new Helper();    
        }      
        return helper;  
    }  
    // other methods and fields...  
}

控制语句

说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间 判断条件来代替。 
反例：判断剩余奖品数量等于 0 时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变 成了负数，这样的话，活动无法终止。

说明：很多 if 语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么 样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？ 
正例： 
// 伪代码如下 
final boolean existed = (file.open(fileName, "w") != null) && (...) || (...); 
if (existed) {     
    ... 
}   
反例： 
if ((file.open(fileName, "w") != null) && (...) || (...)) {     
    ... 
} 

说明：取反逻辑不利于快速理解，并且取反逻辑写法必然存在对应的正向逻辑写法。 
正例：使用 if (x < 628) 来表达 x 小于 628。 
反例：使用 if (!(x >= 628)) 来表达 x 小于 628。

注释规约

说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注 释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高 阅读效率.

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

其他

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

说明：如果想获取更加精确的纳秒级时间值，使用 System.nanoTime()的方式。在 JDK8 中， 针对统计时间等场景，推荐使用 Instant 类。

异常处理

说明：无法通过预检查的异常除外，比如，在解析字符串形式的数字时，不得不通过 catch NumberFormatException 来实现。 
正例：if (obj != null) {...} 
反例：try { obj.method(); } catch (NullPointerException e) {…} 

说明：对大段代码进行 try-catch，使程序无法根据不同的异常做出正确的应激反应，也不利 于定位问题，这是一种不负责任的表现。 
正例：用户注册的场景中，如果用户输入非法字符，或用户名称已存在，或用户输入密码过于 简单，在程序上作出分门别类的判断，并提示给用户。 

说明：关于 RPC 方法返回方式使用 Result 方式的理由：  
1）使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。  
2）如果不加栈信息，只是 new 自定义异常，加入自己的理解的 error message，对于调用 端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输 的性能损耗也是问题。

说明：随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副 本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是组件化。 
正例：一个类中有多个 public 方法，都需要进行数行相同的参数校验操作，这个时候请抽取： private boolean checkParam(DTO dto) {...}

日志规约

import org.slf4j.Logger;  
import org.slf4j.LoggerFactory; 
private static final Logger logger = LoggerFactory.getLogger(Abc.class);  

正例：mppserver 应用中单独监控时区转换异常，如：                                 
mppserver_monitor_timeZoneConvert.log 
说明：推荐对日志进行分类，如将错误日志和业务日志分开存放，便于开发人员查看，也便于 通过日志对系统进行及时监控。 

说明：logger.debug("Processing trade with id: " + id + " and symbol: " + symbol); 如果日志级别是 warn，上述日志不会打印，但是会执行字符串拼接操作，如果 symbol 是对象， 会执行 toString()方法，浪费了系统资源，执行了上述操作，最终日志却没有打印。 
正例：（条件）建设采用如下方式 
if (logger.isDebugEnabled()) {    logger.debug("Processing trade with id: " + id + " and symbol: " + symbol);   }       
正例：（占位符） logger.debug("Processing trade with id: {} and symbol : {} ", id, symbol);

正例：<logger name="com.taobao.dubbo.config" additivity="false"> 

正例：logger.error(各类参数或者对象 toString() + "_" + e.getMessage(), e); 

说明：大量地输出无效日志，不利于系统性能提升，也不利于快速定位错误点。记录日志时请 
思考：这些日志真的有人看吗？看到这条日志你能做什么？能不能给问题排查带来好处？ 

说明：注意日志输出的级别，error 级别只记录系统逻辑出错、异常或者重要的错误信息。
上一篇下一篇

猜你喜欢

热点阅读