主要参考阿里出品的《码出高效 阿里巴巴java开发手册 终极版》

前言

  1. 发现已有代码与本规约冲突的，需要重构，可逐步改进。
  2. 代码写出来，除了能够实现正确的功能，更多的，是给人阅读的，因为软件需要不停的维护。

本规约的 java 规范

主要参考阿里出品的《码出高效 阿里巴巴java开发手册 终极版》，以下简称《码出高效》。

本规约的 js 规范

Airbnb JavaScript Style Guide -> js 编码规范参考

  • 与该规范不一样的地方：缩进，保留 WebStorm 的默认行为，即一个 tab 对应 4 个空格。编码时使用 tab 键进行缩进即可。

关键目的

  1. 见名知义
  2. 代码自解释
  3. 易读
    • 美女，秀色可餐，养眼，大家都爱看。
    • 代码如人，干净利索，赏心悦目，读起来是一种享受。
  4. 易维护。不要一看就想骂 ^_^
  5. 养成好的习惯，受益终生。

关键差异

条目 阿里 团队 备注
抽象类命名 使用 Abstratc 或 Base 开头 只用 Abstratc 开头
常量命名 全部大写，单词间用下划线隔开 lowerCamelCase 风格，驼峰形式 全部大写不利于阅读，但是跟一般的规范冲突，如果有理由，本条可修改
枚举成员名称 需要全大写，单词间用下划线隔开，枚举其实就是特殊的常量类 同上 同上

命名风格

  1. 代码中的命名不能包括特殊字符，如下划线、美元符号等。
  2. 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
    • 例外：alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。
    • 说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。
    • 注意，即使纯拼音命名方式也要避免采用。
  3. 类名使用 UpperCamelCase 风格，必须遵从驼峰形式，但以下情形例外：DO/BO/DTO/VO/AO。
  4. 方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，遵从驼峰形式。
  5. html、js、css 文件，命名规则，统一使用 lowerCamelCase 风格，遵从驼峰形式。
  6. 常量命名使用 lowerCamelCase 风格，遵从驼峰形式。力求语义表达完整清楚，不要嫌名字长。注：本条与《码出高效》不一致。
  7. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
  8. 中括号是数组类型的一部分，数组定义如下：String[] args;
  9. 抽象类命名使用 Abstract 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。
  10. 杜绝完全不规范的缩写，避免望文不知义。
  11. 为了达到代码自解释的目标，任何定义编程元素在命名时使用尽量完整单词组合来表达其意。正例：从远程仓库拉取代码的类命名为 PullCodeFromRemoteRepository。
  12. POJO 类中布尔类型的变量，都不要加 is，否则部分框架解析会引起序列化错误。注：现有代码里有一部分与该规则冲突，需要重构。
  13. 如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计理念。
  14. 接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。
  15. 接口和实现类的命名，对于Service和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别。正例：CacheServiceImpl 实现 CacheService 接口。
  16. 枚举类名建议带上Enum后缀，枚举成员名称，统一使用 lowerCamelCase 风格，遵从驼峰形式，这样方便阅读。注：本条与《码出高效》不一致。

各层命名规约

Service/DAO 层方法命名规约

  1. 获取单个对象的方法用 get 做前缀
  2. 获取多个对象的方法用 list 做前缀
  3. 获取统计值的方法用 count 做前缀
  4. 插入的方法用 save/insert 做前缀
  5. 删除的方法用 remove/delete 做前缀
  6. 修改的方法用 update 做前缀

领域模型命名规约

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

常量定义

  1. 常量定义不允许使用魔法值，（即未经定义的常量）直接出现在代码中。

    1
    2
    3
    4
    5
    6
    //反例
    int priceTable[] = new int[16];

    //正例
    static final int PRICE_TABLE_MAX = 16;
    int priceTable[] = new int[PRICE_TABLE_MAX];

  2. long或者Long初始赋值时，使用大写的L，不能是小写的l，小写容易跟数字1混淆，造成误解。说明：Long a = 2l; 写的是数字的21，还是Long型的2?

  3. 不要使用一个常量类维护所有常量，按常量功能进行归类，分开维护。 说明：大而全的常量类，非得使用查找功能才能定位到修改的常量，不利于理解和维护。正例：
    • 缓存相关常量放在类 CacheConsts 下
    • 系统配置相关常量放在类ConfigConsts下

代码格式

  1. 大括号的使用约定。如果是大括号内为空，则简洁地写成 {} 即可，不需要换行；如果是非空代码块则：
    • 左大括号前不换行
    • 左大括号后换行
    • 右大括号前换行
    • 右大括号后还有 else, catch 等代码则不换行
    • 表示终止的右大括号后必须换行
  2. 左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格。反例：if (空格a == b空格)
  3. if/for/while/switch/do 等保留字与括号之间都必须加空格。
  4. 任何二目、三目运算符的左右两边都需要加一个空格。说明：运算符包括赋值运算符 =、逻辑运算符 &&、加减乘除符号等。

  5. 采用4个空格缩进，禁止使用 tab 字符。说明：如果使用 tab 缩进，必须设置 1 个 tab 为 4个空格。IDEA 设置 tab 为 4个空格时，请勿勾选 Use tab character；而在 eclipse 中，必须勾选 insert spaces for tabs。

    • 正例：（涉及1-5点）
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      public static void main(String[] args) {
          // 缩进4个空格
          String say = "hello";
          // 运算符的左右必须有一个空格
          int flag = 0;
          // 关键词if与括号之间必须有一个空格，括号内的f与左括号，0与右括号不需要空格
          if (flag == 0) {
              System.out.println(say);
          }
          // 左大括号前加空格且不换行；左大括号后换行
          if (flag == 1) {
              System.out.println("world");
          // 右大括号前换行，右大括号后有else，不用换行
          } else {
              System.out.println("ok");
          // 在右大括号后直接结束，则必须换行
          }
      }

  6. 注释的双斜线与注释内容之间有且仅有一个空格。

  7. 单行字符数限不超过 120 个（可适当放宽该约束），超出需要换行时，遵循如下原则：

    • 第二行相对第一行缩进 4 个空格，或者遵从 IDEA Ctrl+Alt+L 的代码格式化结果（以下缩进了8个空格），从第三行开始不再继续缩进，即保持与第二行排列整齐，参考示例。
    • 运算符与下文一起换行。
    • 方法调用的点符号与下文一起换行。
    • 方法调用时，多个参数，需要换行时，在逗号后进行。
    • 在括号前不要换行，见反例。 
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      private void test() {
          StringBuffer sb = new StringBuffer();
          // 正例：
          // 超过120个字符的情况下，换行缩进4个空格，点号和方法名称一起换行
          sb.append("zi").append("xin")//...
                  .append("huang")//...
                  .append("huang")//...
                  .append("huang");
          // 反例：
          // 超过120个字符的情况下，不要在括号前换行
          sb.append("zi").append("xin")./*...*/append
                  ("huang");
          // 参数很多的方法调用可能超过120个字符，不要在逗号前换行
          method(args1, args2, args3 /*,...*/
                  , argsX);
      }

  8. 方法参数在定义和传入时，多个参数逗号后边必须加空格。 正例：下例中实参的”a”,后边必须要有一个空格。method(“a”, “b”, “c”);

  9. IDE的text file encoding 设置为 UTF-8; IDE中文件的换行符使用Unix格式，不要使用Windows格式。

  10. 没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。 正例：

    1
    2
    3
    4
    int a = 3;
    long b = 4L;
    float c = 5F;
    StringBuffer sb = new StringBuffer();
    • 说明：增加 sb 这个变量，如果需要对齐，则给a、b、c都要增加几个空格，在变量比较多的情况下，是一种累赘的事情。

空行

  1. 方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行。
  2. 相同业务逻辑和语义之间不需要插入空行。
  3. 没有必要插入多个空行进行隔开。
  4. 不要插入没有必要的空行，如方法结束前的返回语句后面。

to be continued

做到以上规范是基本要求。后续还会添加剩下的规范。