阿里巴巴Java开发手册（格式规约篇）——查自己的漏-补自己的缺

一、编程规约

(三) 格式规约

1. 【强制】大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：

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

2. 【强制】 左括号和后一个字符之间不出现空格；同样，右括号和前一个字符之间也不出现空格。详见第5条下方正例提示。

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

4. 【强制】任何运算符左右必须加一个空格。 说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号、三目运行符等。

5. 【强制】代码块缩进4个空格，如果使用tab缩进，请设置成1个tab为4个空格。 正例： （涉及1-5点

public static void main(String args[]) {
    String say = "hello";
    // 运算符的左右必须有一个空格
    int flag = 0;
    // 关键词if与括号之间必须有一个空格，括号内f与左括号，1与右括号不需要空格
    if (flag == 0) {
        System.out.println(say);
    } 

    // 左大括号前加空格且不换行；左大括号后换行
    if (flag == 1) {
        System.out.println("world");
    // 右大括号前换行，右大括号后有else，不用换行
    } else {
        System.out.println("ok");
    // 右大括号做为结束，必须换行
    }
}

(八）注释规约

1.【强制】类、类属性、类方法的注释必须使用Javadoc规范。使用/** 内容 */格式，不得使用// xxx方式。

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

2.【强制】所有的抽象方法（包括接口中的方法）必须用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

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

5.【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。

 二、异常日志

（一）异常处理

4.【强制】捕获异常时为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者必须处理异常，将其转化为用户可以理解的内容。

7.【强制】不要在finally块中使用return。

　　说明：finally块中的return返回后方法结束执行，不会再执行try块中的return语句。

11.【推荐】定义时区分unchecked/checked异常，避免直接抛出new RuntimeException()，更不允许抛出Exception或者Throwable，应使用有业务含义的自定义异常。推荐业界已定义过的自定义异常，如：DAOException/ServiceException等。

12.【参考】对于公司外的http/api开放接口必须使用”错误码“；而应用内部推荐异常抛出；跨应用间RPC调用优先考虑使用Result方式，封装isSuccess()方法、”错误码“、”错误简短信息“。

　　说明：关于RPC方法返回方式使用Result方式的理由：

　　1）使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。

　　2）如果不加栈信息，只是new 自定义异常，加入自己的理解error message，对于调用端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。

（二）日志规约

1.【强制】应用中不可直接使用日志系统（Log4j、Logback）中的API,而应依赖使用日志框架SLF4J中的API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。

　　

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

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

　3.【强制】应用中的扩展日志（如打点、临时监控、访问日志等）命名方式：

　　appName_logType_logName.log。

　　logType:日志类型，如stats/monitor/access等；logName:日志描述。这种命名的好处；通过文件名就可以知道日志文件属于什么应用，什么类型，什么目的，也有利于归类查找。

　　正例：mppserver应用中单独监控时区转化异常，如：

　　mppserver_monitor_timeZoneConvert.log

　　说明：推荐对日志进行分类，如将错误日志和业务日志分开存放，便于开发人员查看，也便于通过日志对系统进行及时监控。

　4.【强制】对trace/deug/info级别的日志输出，必须使用条件输出形式或者使用占位符的方式。

　　说明：

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 );

　6.【强制】异常信息应包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么通过关键字throws往上抛出。

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

五、MySQL数据库

（三）SQL语句

　　1.【强制】不要使用count(列名)或count(常量)来替代count(*),count(*)是SQL92定义的标准统计行数的语法，跟数据库无关，跟NULL和非NULL无关。

　　说明：count（*）会统计值为NULL的行，而count（列名）不会统计此列为NULL值的行。

　　2.【强制】当某一列的值全是NULL时，count(col)的返回结果为0，但sum(col)的返回结果为NULL,因此使用sum()时需注意NPE问题。

　　正例：SELECT IF( ISNULL( SUM(g) ), 0 ,SUM(g)) FROM table;