• 主要参考阿里出品的《码出高效 阿里巴巴java开发手册 终极版》，以下简称《码出高效》。
  • 本文仅列出最基本的要求。未列出的，需要直接参考阿里的《码出高效》

js 规范，保留与 Airbnb JavaScript Style Guide -> js 编码规范参考 一致
与该规范不一样的地方：缩进，保留 WebStorm 的默认行为，即一个 tab 对应 4 个空格。编码时使用 tab 键进行缩进即可。

前言

  1. 发现已有代码与本规约冲突的，可逐步重构，正好需要修改与本规约冲突的代码时，需要考虑是否重构，重构与否，需要与上级讨论之后再决定，避免重构之后测试不到位引发线上 BUG。
  2. 代码写出来，除了能够实现正确的功能，更多的，是给人阅读的，因为软件需要不停的维护。

领域模型命名规约

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

相关名词

  1. POJO（Plain Ordinary Java Object）：在本规约中，POJO 专指只有 setter / getter / toString 的简单类，包括 DO / DTO / BO / VO 等。
  2. DO（Data Object）：阿里巴巴专指数据库表一一对应的 POJO 类。此对象与数据库表结构一一对应，通过 DAO 层向上传输数据源对象。
  3. PO（Persistent Object）：也指数据库表一一对应的 POJO 类。此对象与数据库表结构一一对应，通过 DAO 层向上传输数据源对象。
  4. DTO（Data Transfer Object ）：数据传输对象，Service 或 Manager 向外传输的对象。
  5. BO（Business Object）：业务对象，可以由 Service 层输出的封装业务逻辑的对象。
  6. Query：数据查询对象，各层接收上层的查询请求。注意超过 2 个参数的查询封装，禁止使用 Map 类来传输。
  7. VO（View Object）：显示层对象，通常是 Web 向模板渲染引擎层传输的对象。

最基本的也是平常最应该遵守的规则

  1. 见名知意
  2. 代码自解释
  3. 易读
    • 美女，秀色可餐，养眼，大家都爱看。
    • 代码如人，干净利索，赏心悦目，读起来是一种享受。
  4. 易维护。不要一看就想骂 ^_^
  5. 养成好的习惯，受益终生。
  6. 属性和方法名，用小驼峰命名法：第一个单词的首字母小写，后面每个单词的首字母大写，并且单词之间不使用任何分隔符。例如：firstName、calculateArea、customerInfo
  7. 类名，用大驼峰命名法
  8. todo 及时清理
  9. 除了养成习惯写必要的备注之外，随着代码的迭代，还要及时更新备注，以使备注与当前代码逻辑匹配。不正确的备注比没有备注更要命
  10. 用不上的变量，及时清理，如果考虑到将来可能会用到，也需要先注释掉，不要存在定义了但没有用上的变量
  11. 注重：代码整洁性、可读性、可维护性、健壮性

命名风格

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

各层命名规约

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. 不要插入没有必要的空行，如方法结束前的返回语句后面。

DRY

一定要避免相同的内容出现在不同的文件

  • 这些相同的内容指的是：
    • java 后端，可以抽离出来当作公共方法，或者直接抽离到一个具体的类
    • 前端页面，可以抽离出来，如 jsp 的包含文件，可当作“组件”
    • 小程序，可以抽离出来，以组件的方式共用，或者以 modal、include 的方式出现
    • js，可以抽离出来当作公共方法，或者归类到一个现有 class 下
  • 如果在两个业务板块都有用到，一定是抽离出来放到一个公共文件，再适当通过变量、参数加以控制

约定

IDE

  • 请关闭 IDE 的保存时自动格式化功能
  • jsp 或 小程序 的代码，被 IDE 格式化之后，可能会变得非常乱，还不如手工调整
  • 即使是后端 JAVA 代码，也有不需要格式的地方，虽然比较少
  • 建议在提交前对代码做格式化检查
  • 如果是对整个文件做格式化，那么一定不要与代码修改混在一起提交，格式化先修改且及时提交，然后再修改代码，这样方便后期代码走查以及问题排查，切记切记
    • 之前的后端 JAVA 代码，格式比较混乱的，如果需要修改，建议先用 IDEA 格式化一次（Ctrl + Alt + L），然后直接提交，提交备注写：仅格式化代码，无逻辑修改，提交之后再修改
    • 之前的代码，包括前后端，好多命名是不规范的，如果需要修改相关代码，实在看不过去，建议先重构一番，IDEA 系列 IDE 是选中变量、或者方法名、或者选中类文件，Ctrl + F6，重构完成第一时间提交，提交之后再修改。提交备注：简单重构，无逻辑修改
  • 要善于利用 IDEA 和 WebStorm 的单词拼写检查功能，有波浪线的地方，需要关注

对类名、方法名、变量名进行重构

危险的行为，特别是跨多个文件，可能存在一定的风险，请谨慎对待

  • 提交前一定要检查每一处修改，并且有充分的测试，确保重构没有问题才能提交
  • 变更名或方法名重构，是全局搜索替换，可能替换了不该替换的，可能无法在编译期发现问题，所以一定要仔细检查和测试
  • 重构之后，可能会有变量名冲突或类调用冲突，这还好说，编译会报错，很容易发现问题
  • 当然，实际上，绝大多数情况都是很简单的，涉及到的修改点也并不多，很容易验证重构是否有问题
  • 如果确实拿不准是否要重构，或者重构之后是否有风险，先不要重构，或者请示同事、和同事一起探讨

IDEA 和 WebStorm 支持部分代码格式化

  • 虽然不建议对整个文件做代码格式化，但是一定要对需要做格式化的代码局部格式化，在选中代码块的情况下，Ctrl + Alt + L
  • 通常，后端 Java 代码，以及前端的 Js 代码，对整个文件做格式化是没有问题的，对于部分格式化后反而变乱的代码，提交之前恢复即可

前后端业务逻辑

  • 能在后端完成的业务逻辑，一定不要放到前端处理，前端只处理只能在前端处理的业务逻辑
  • 后端，善用全局缓存数据

同一业务下的多个类名、多个数据库表名、多个变量名

  1. 具有相同部分的类名或数据库表名：把相同部分统一放到前面，这样，如果是类，在 ide 会在一起显示，如果是数据库表，也会显示在一起，方便查阅和维护。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    // 类
    // 正例
    PassportBuyer
    PassportVendor
    PassportOpenCard

    // 反例
    BuyerPassport
    VendorPassport
    OpenCardPassport

  2. 具有相同部分的变量或属性名，把相同部分统一放到前面，且变量或属性放到一起，方便查阅和维护，在逻辑上也能清楚地知道有哪些相同或相近的地方

属性字段、实例名

  1. POJO，属性统一放到最前面，后面才是 setter 或 getter，如果用到 lombok 的 @Data 注解，则没有这个问题

  2. 针对数据库表对应的 POJO 实例变量名，直接去掉前面的前缀 Tb，保留后面部分，首字母小写即可，如果同一个方法或类的属性需要定义多个相同 POJO 变量，则在后面添加业务相关的单词来区分

    1
    2
    3
    4
    5
    6
    TbDrawWinnerListImportBase drawWinnerListImportBase
    TbDrawWinnerListImportWinner drawWinnerListImportWinner
       
    // 多个相同 POJO 实例命名举例
    TbDrawWinnerListImportBatch drawWinnerListImportBatchNew // 新实例
    TbDrawWinnerListImportBatch drawWinnerListImportBatchFromDb // 查询数据库得到的实例

  3. 普通类的实例变量名，将类名首字母由大写改为小写即可，同理，如果同一个方法或类的属性需要定义多个相同类的实例变量，则在后面添加业务相关的单词来区分

    1
    WinnerListColumnCheckView winnerListColumnCheckView

  4. 对于响应类，一般同一个请求，只有一个返回对象，如果返回对象对应的类名以 response 结尾，则可以简单的命名为 response

    1
    ImportWinnerListResponse response

  5. 同理，对于请求类，如果请求对象对应的类名以 request 结尾，则可以简单的命名为 request

    1
    GetWinnerListVersionTipsRequest request