Java 开发手册

Java 开发手册

编程规范

命名风格

1. 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
2. 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式，即使纯拼音命名方式也要避免采用。
3. 类名使用大驼峰拼写法（UpperCamelCase）风格。
4. 方法名、参数名、成员变量、局部变量都统一使用小驼峰拼写法（lowerCamelCase）风格。
5. 常量命名全部大写，单词间用下划线隔开。
6. 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。
7. 如果模块、接口、类、方法使用了设计模式，在命名时需体现出具体模式。
8. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
9. 杜绝完全不规范的缩写，避免望文不知义。
10. 为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意。
11. 类型与中括号紧挨相连来表示数组。
12. POJO 类中布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列化错误。
13. 接口类中的方法和属性不要加任何修饰符号 （public 也不要加），保持代码的简洁性，并加上有效的 Javadoc 注释。尽量不要在接口里定义变量，如果一定要定义变量，一定是与接口方法相关，并且是整个应用的基础常量。
14. 接口和实现类的命名有两套规则：
    • 对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用 Impl 的后缀与接口区别。
    • 如果是形容能力的接口名称，取对应的形容词为接口名（通常是 –able 的形式）。
15. 枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。枚举其实就是特殊的类，域成员均为常量，且构造方法被默认强制是私有。
16. 各层命名规约：
    • Service / DAO 层方法命名规约：
      • 获取单个对象的方法用 get 做前缀。
      • 获取多个对象的方法用 list 做前缀，复数形式结尾。
      • 获取统计值的方法用 count 做前缀。
      • 插入的方法用 save / insert 做前缀。
      • 删除的方法用 remove / delete 做前缀。
      • 修改的方法用 update 做前缀。
    • 领域模型命名规约：
      • 数据对象： xxxDO ，xxx 为数据表名。
      • 数据传输对象： xxxDTO ，xxx 为业务领域相关的名称。
      • 展示对象： xxxVO ，xxx 一般为网页名称。
      • POJO 是 DO / DTO / BO / VO 的统称，禁止命名成 xxxPOJO 。

常量定义

1. 不允许任何魔法值 （即未经预先定义的常量） 直接出现在代码中。
2. 在 long 或者 Long 赋值时，数值后使用大写的 L ，不能是小写的 l ，小写容易跟数字 1 混淆，造成误解。
3. 不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。
4. 常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
   • 跨应用共享常量：放置在二方库中，通常是 client . jar 中的 constant 目录下。
   • 应用内共享常量：放置在一方库中，通常是子模块中的 constant 目录下。
   • 子工程内部共享常量：即在当前子工程的 constant 目录下。
   • 包内共享常量：即在当前包下单独的 constant 目录下。
   • 类内共享常量：直接在类内部 private static final 定义。
5. 如果变量值仅在一个固定范围内变化用 enum 类型来定义。

代码格式

1. 大括号的使用约定：
   • 如果是大括号内为空，则简洁地写成 {} 即可，不需要换行。
   • 如果是非空代码块则：
     • 左大括号前不换行。
     • 左大括号后换行。
     • 右大括号前换行。
     • 右大括号后还有 else 等代码则不换行； 表示终止的右大括号后必须换行。
2. 左小括号和字符之间不出现空格，右小括号和字符之间也不出现空格，而左大括号前需要空格。
3. if / for / while / switch / do 等保留字与括号之间都必须加空格。
4. 任何二目、三目运算符的左右两边都需要加一个空格。
5. 采用 4 个空格缩进，禁止使用 tab 字符。如果使用 tab 缩进，必须设置 1 个 tab 为 4 个空格。
6. 注释的双斜线与注释内容之间有且仅有一个空格。
7. 单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：
   • 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进。
   • 运算符与下文一起换行。
   • 方法调用的点符号与下文一起换行。
   • 方法调用中的多个参数需要换行时，在逗号后进行。
   • 在括号前不要换行。
8. 方法参数在定义和传入时，多个参数逗号后边必须加空格。
9. IDE 的 text file encoding 设置为 UTF -8 ; IDE 中文件的换行符使用 Unix 格式，不要使用 Windows 格式。
10. 单个方法包括方法签名、结束右大括号、方法内代码、注释、空行、回车及任何不可见字符在内的总行数不超过 80 行。
11. 没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。
12. 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性，但没有必要插入多个空行进行隔开。

控制语句

1. 在一个 switch 块内，每个 case 要么通过 break / return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使空代码。
2. 在 if / else / for / while / do 语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式。
3. 在高并发场景中，避免使用“等于”判断作为中断或退出的条件。如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件来代替。
4. 表达异常的分支时，少用 if - else 方式。如果非得使用 if () … else if () … else … 方式表达逻辑，不要超过 3 层。超过 3 层的 if - else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现。
5. 除常用方法（如 getXxx / isXxx ）等外，不要在条件判断中执行其它复杂的语句。可以将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
6. 循环体中的语句要考量性能，以下操作尽量移至循环体外处理：
   • 定义对象、变量。
   • 获取数据库连接。
   • 进行不必要的 try - catch 操作 （ 这个 try - catch 可以移至循环体外 ） 。
7. 避免采用取反逻辑运算符。取反逻辑不利于快速理解，并且取反逻辑写法必然存在对应的正向逻辑写法。
8. 接口入参保护，这种场景常见的是用作批量操作的接口。