本规范参考了阿里巴巴Java开发手册.pdf,统一Java代码的格式和风格有利于写出高质量的代码(主要是易读性),在这里引用里面的一段话:

手册的愿景是码出高效码出质量。现代软件架构的复杂性需要协同开发完成,如何高效地协同呢?无规矩不成方圆,无规范难以协同,比如,制订交通法规表面上是要限制行车权,实际上是保障公众的人身安全,试想如果没有限速,没有红绿灯,谁还敢上路行驶?对软件来说,适当的规范和标准绝不是消灭代码内容的创造性、优雅性,而是限制过度个性化,以一种普遍认可的统一方式一起做事,提升协作效率,降低沟通成本。代码的字里行间流淌的是软件系统的血液,质量的提升是尽可能少踩坑,杜绝踩重复的坑,切实提升系统稳定性,码出质量。

代码格式与风格

格式规范

  • 所有代码(包括配置文件)必须使用UTF-8编码格式,禁止使用其他编码(如:GBK)
  • 必须采用4个空格缩进,禁止使用tab字符
  • 注释的双斜线与注释内容之间有且仅有一个空格
  • 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性(任何情形,没有必要插入多个空行进行隔开)
  • 单行字符数限制不超过160个(现在显示屏分辨率都很高),当需要换行是必须保证换行后的代码清晰易读,不可随便乱换行
  • 代码行尾不允许有多余的空格

如果使用IntelliJ IDEA开发工具建议使用以下settings配置: https://gitee.com/LiZhiW/idea-settings-repository.git

命名规范

  • class名称: 必须使用 UpperCamelCase 风格 (首字母大写的驼峰标识)
  • package名称: 必须使用全字小写字符命名
  • 方法名、参数名、成员变量、局部变量: 必须使用 lowerCamelCase 风格 (首字母小写的驼峰标识)
  • 常量: 可以使用“名全部大写,单词间用下划线隔开”或者“UpperCamelCase(首字母大写的驼峰标识)”两种方式命名
  • 异常类: 与class名称相同,但是必须以Exception结尾
  • 抽象类: 与class名称相同,但是必须以AbstractBase开头
  • 接口: 与class名称相同,可以不使用字母I开头,否则会带来许多隐患(如:部分框架解析会引起序列化错误)

除了以上规则以外还要注意以下规范:

  • 代码中的命名均不能以下划线或美元符号(_ $)开始,也不能以下划线或美元符号(_ $)结束
  • POJO类中布尔类型变量都不要加is前缀
  • 各种名称(变量名、类名、方法名)最好使用全英文单词命名,禁止使用拼音和无意义的名称(如: shoujihao、a1)

注释规范

代码注释必须满足Javadoc注释规范,参考Java doc常用的Javadoc介绍

  • class注释: 必须要注明作者创建时间功能描述,如:

    /**
    * 日期工具类, 继承org.apache.commons.lang3.time.DateUtils类<br/>
    * 使用了joda-time时间处理框架<br/>
    * <p/>
    * 作者:LiZW <br/>
    * 创建时间:2016-4-27 21:57 <br/>
    */
    public class DateTimeUtils extends DateUtils {
      ...
    }
  • 方法注释: 必须注明功能描述,可适当对参数和返回值进行描述,如:

    ...
    public class XxxXxx {
      ...
    
      /**
       * 日期型字符串转化为日期,支持格式如下:<br/>
       * "yyyy-MM-dd"<br/>
       * "yyyy-MM-dd HH:mm:ss"<br/>
       * "yyyy-MM-dd HH:mm"<br/>
       *
       * @param str 日期字符串,如:2014/03/01 12:15:10
       * @return 失败返回 null
       */
      public static Date parseDate(Object str) {
          ...
      }
    }
  • 成员变量注释: 成员变量必须在class内部的最上层按照静态成员 > 类成员的顺序编写,成员变量直接不要有空行,必须使用/** 描述... */类型的注释描述成员变量的功能,如:

    ...
    public class XxxXxx {
      ...
    
      /**
       * 创建日期
       */
      protected Date createDate;
      /**
       * 更新日期
       */
      protected Date updateDate;
    }
  • 方法内部注释: 方法内部注释推荐使用单行注释(// 注释...),可以使用/* 多行注释 */,但是禁止使用/** 多行注释 */多行注释,方法内部不允许有连续的多个空行,如:

    ...
    public class XxxXxx {
      ...
      public static Date parseDate(Object str) {
          ...
          // 需要构建树的节点,还未构建到树中的节点
          List<T> allTreeNodeList = getCanBuildTreeNodes(nodes);
          log.info("1 耗时:{}ms", (System.currentTimeMillis() - tmpTime));
          // 清除构建状态
          tmpTime = System.currentTimeMillis();
          clearBuild(allTreeNodeList);
          log.info("2 耗时:{}ms", (System.currentTimeMillis() - tmpTime));
          // 查找所有根节点
          tmpTime = System.currentTimeMillis();
          List<T> rootNodeList = findRootNode(allTreeNodeList);
          log.info("3 耗时:{}ms", (System.currentTimeMillis() - tmpTime));
          // 刷新还未构建到树中的节点,减少循环次数
          tmpTime = System.currentTimeMillis();
          List<T> noBuildTreeNodeList = refreshNoBuildNodes(allTreeNodeList);
          log.info("4 耗时:{}ms", (System.currentTimeMillis() - tmpTime));
          // 循环根节点,构建多棵树
          tmpTime = System.currentTimeMillis();
          buildTree(rootNodeList, noBuildTreeNodeList);
          log.info("5 耗时:{}ms", (System.currentTimeMillis() - tmpTime));
          // 刷新还未构建到树中的节点,减少循环次数
          noBuildTreeNodeList = refreshNoBuildNodes(noBuildTreeNodeList);
          final long endTime = System.currentTimeMillis();
          // 校验构建是否正确
          ...
      }
    }

编码约束

  • 接口类中的方法和属性不要加任何修饰符号(public 也不要加),保持代码的简洁性,并加上有效的Javadoc注释
  • 不允许任何魔法值(即未经预先定义的常量)直接出现在代码中
  • 所有的覆写方法,必须加@Override注解。
  • 定义DO/DTO/VO等POJO类时,不要设定任何属性默认值
  • Controller/Service/DAO/Mapper中,
    • 获取单个对象的方法用get做前缀
    • 获取多个对象的方法用find/query/list做前缀而且使用复数形式结尾(如:findUsers)
    • 获取统计值的方法用count做前缀
    • 插入的方法用save/insert做前缀
    • 删除的方法用remove/delete/del做前缀
    • 修改的方法用update做前缀
  • 访问类型的静态变量或静态方法应该直接使用类名来访问,禁止使用类的对象引用访问(无谓增加编译器解析成本)
  • 在long或者Long赋值时,数值后使用大写的L,不能是小写的l,小写容易跟数字1混淆,造成误解
    • 同理,在float或者Float赋值时,数值后使用大写的F
    • 同理,在double或者Double赋值时,数值后使用大写的D
  • 枚举类名带上Enum后缀,枚举成员名称需要全大写,单词间用下划线隔开
  • 不要使用一个常量类维护所有常量,要按常量功能进行归类,分开维护
  • 未完成的功能必须加上TODO 描述...进行标记,实现功能后必须删除该标记

IDEA警告

使用IntelliJ IDEA编写代码时,按照IDEA的警告提示必须要修复IDEA的所有警告信息,除了以下警告之外:

  • 类、成员变量、方法上的访问性修饰符的可用范围
  • 类、成员变量、方法从未使用过
  • 方法返回值从未接收过
  • 方法参数总是使用的同一个值调用
  • …类似的警告

IDEA警告正例

正例

IDEA警告反例

反例

文档更新时间: 2019-08-14 20:33   作者:lizw