目录

前言

1.编程规约

1.1 命名风格

1.2 常量定义

1.3 代码格式

1.4 OOP 规约

1.5 日期时间

1.6 集合处理

1.7 并发处理 

1.8 控制语句

1.9 注释规约

1.10 前后端规约

1.11 其他

---

前言

规约依次分为【重要】、【建议】、【参考】，整理开发规范的目的在于写出更加高效、质量更高的代码。

1.编程规约

1.1 命名风格

1. 【重要】所有编程相关的命名既不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

反例：_name / $name / name_ / name$

2.【重要】所有编程相关的命名不能使用拼音与英文混合命名，更不能使用中文直接命名。

说明：遵循英文拼写和语法更易于码农理解代码，也可以使用英文缩写

正例：使用 alibaba /  aliyun / PIN ( Personal Identity number 个人识别码)

反例：ShouFeiRecord【记录】/ getGeRenInfo 【获取个人信息】

 3.【重要】代码和注释避免使用侮辱性词语。

正例：blockList / allowList / secondary

反例：blackList / whiteList / BT / SB 

 4.【重要】类名使用大驼峰式命名法（upper camel case），每一个单词的首字母都采用大写字母。DO / PO / DTO / BO / VO / UID 等除外。

正例：UserDO / FirstName / LastName / HtmlDTO

反例：userDO / firstName / lastName / htmlDTO

5. 【重要】方法名、参数名、成员变量、局部变量都使用 小驼峰式命名法（lower camel case），第一个单词以小写字母开始，第二个单词的首字母大写。

正例：userDO / firstName / lastName / htmlDTO

---

6.【重要】常量命名应该全部大写，单词之间使用下划线分隔，力求语义表达完整清楚，名字可以长一些。

正例：MAX_STOCK_COUNT / CACHE_EXPIRED_TIME

反例：MAX_COUNT / EXPIRED_TIME

7.【重要】抽象类命名使用Abstract 或 Base 开头；异常类命名使用 Exception 结尾，测试类命名以它要 测试的类的名称开始，以 Test 结尾。

8.【重要】类型与中括号紧挨相连定义数组。

正例：定义整形数组 int[] arrayDemo。

反例：在 main 参数中，使用 String args[] 来定义。

9.【重要】POJO 类中的任何布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列化错误。

说明：本文 MySQL 规约中的建表约定第 1 条，表达是与否的变量采用 is_xxx 的命名方式，所以需要在 设置从 is_xxx 到 xxx 的映射关系。

反例：定义为布尔类型 Boolean isDeleted 的字段，它的 getter 方法也是 isDeleted()，部分框架在反向解析时，“误以 为”对应的字段名称是 deleted，导致字段获取不到，得到意料之外的结果或抛出异常。

10.【重要】包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形 式，但是类名如果有复数含义，类名可以使用复数形式。

正例：应用工具类包名为 com.alibaba.ei.kunlun.aap.util；类名为 MessageUtils（此规则参考 spring 的框架结构）。

---

11.【重要】避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名，使可理 解性降低。

说明：子类、父类成员变量名相同，即使是 public 也是能够通过编译，而局部变量在同一方法内的不同代码块中同名 也是合法的，但是要避免使用。对于非 setter / getter 的参数名称也要避免与成员变量名称相同。

反例：

public class ConfusingName { 

    protected int stock; 

    protected String alibaba; 

    // 非 setter/getter 的参数名称，不允许与本类成员变量同名 

    public void access(String alibaba) { 

        if (condition) { 

            final int money = 666; 

            // ... 

        } 

        for (int i = 0; i < 10; i++) { 

            // 在同一方法体中，不允许与其它代码块中的 money 命名相同 

            final int money = 15978; 

            // ... 

        } 

    } 

} 

class Son extends ConfusingName { 

    // 不允许与父类的成员变量名称相同 

    private int stock; 

} 

12.【重要】杜绝完全不规范的英文缩写，避免望文不知义。

反例：AbstractClass“缩写”成 AbsClass；condition“缩写”成 condi；Function“缩写”成 Fu，此类随意缩写 严重降低了代码的可阅读性。

13.【建议】为了达到代码自解释的目标，任何自定义编程元素在命名时，使用完整的单词组合来表达。

正例：在 JDK 中，对某个对象引用的 volatile 字段进行原子更新的类名为 AtomicReferenceFieldUpdater。

反例：常见的方法内变量为 int a; 的定义方式。

14.【建议】在常量与变量命名时，表示类型的名词放在词尾，以提升辨识度。

正例：startTime / workQueue / nameList / TERMINATED_THREAD_COUNT

反例：startedAt / QueueOfWork / listName / COUNT_TERMINATED_THREAD

15.【建议】如果模块、接口、类、方法使用了设计模式，在命名时要体现出具体模式。

说明：将设计模式体现在名字中，有利于阅读者快速理解架构设计思想。

正例：public class OrderFactory;

           public class LoginProxy;

           public class ResourceObserver;

---

16.【建议】接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上 有效的 Javadoc 注释。尽量不要在接口里定义常量，如果一定要定义，最好确定该常量与接口的方法 相关，并且是整个应用的基础常量。

正例：接口方法签名 void commit();

           接口基础常量 String COMPANY = "alibaba";

反例：接口方法定义 public abstract void commit();

说明：JDK8 中接口允许有默认实现，那么这个 default 方法，是对所有实现类都有价值的默认实现。

17.接口和实现类的命名有两套规则：

1）【重要】对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用 Impl 的后缀 与接口区别。

正例：CacheServiceImpl 实现 CacheService 接口。

2）【建议】如果是形容能力的接口名称，取对应的形容词为接口名（通常是 –able 结尾的形容词）。

正例：AbstractTranslator 实现 Translatable。

18.【参考】枚举类名带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。

说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

正例：枚举名字为 ProcessStatusEnum 的成员名称：SUCCESS / UNKNOWN_REASON

19.【参考】各层命名规约：

A）Service / DAO 层方法命名规约：

        1）获取单个对象的方法用 get 做前缀。

        2）获取多个对象的方法用 list 做前缀，复数结尾，如：listObjects

        3）获取统计值的方法用 count 做前缀。

        4）插入的方法用 save / insert 做前缀。

        5）删除的方法用 remove / delete 做前缀。

        6）修改的方法用 update 做前缀。

B）领域模型命名规约：

        1）数据对象：xxxDO，xxx 即为数据表名。

        2）数据传输对象：xxxDTO，xxx 为业务领域相关的名称。

        3）展示对象：xxxVO，xxx 一般为网页名称。

        4）POJO 是 DO / DTO / BO / VO 的统称，禁止命名成 xxxPOJO。

---

1.2 常量定义

1.【重要】不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。

反例：

// 开发者 A 定义了缓存的 key。 
String key = "Id#taobao_" + tradeId; 
cache.put(key, value); 

// 开发者 B 使用缓存时直接复制少了下划线，即 key 是"Id#taobao" + tradeId，导致出现故障。 
String key = "Id#taobao" + tradeId; 
cache.get(key); 

2.【重要】long 或 Long 赋值时，数值后使用大写 L，不能是小写 l，小写容易跟数字混淆，造成误解。

说明：public static final Long NUM = 2l; 写的是数字的 21，还是 Long 型的 2？

3.【重要】浮点数类型的数值后缀统一为大写的 D 或 F。

正例：

public static final double HEIGHT = 175.5D; 

public static final float WEIGHT = 150.3F; 

4.【建议】不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。

说明：大而全的常量类，杂乱无章，使用查找功能才能定位到要修改的常量，不利于理解，也不利于维护。

正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 SystemConfigConsts 下。

5.【建议】常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常 量、类内共享常量。

1）跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。

2）应用内共享常量：放置在一方库中，通常是子模块中的 constant 目录下。

反例：易懂常量也要统一定义成应用内共享常量，两个程序员在两个类中分别定义了表示“是”的常量：

      类 A 中：public static final String YES = "yes";

      类 B 中：public static final String YES = "y";

      A.YES.equals(B.YES)，预期是 true，但实际返回为 false，导致线上问题。

3）子工程内部共享常量：即在当前子工程的 constant 目录下。

4）包内共享常量：即在当前包下单独的 constant 目录下。

5）类内共享常量：直接在类内部 private static final 定义。

---

6.【建议】如果变量值仅在一个固定范围内变化用 enum 类型来定义。

说明：如果存在名称之外的延伸属性应使用 enum 类型，下面正例中的数字就是延伸信息，表示一年中的第几个季节。

正例：

public enum SeasonEnum { 

    SPRING(1), SUMMER(2), AUTUMN(3), WINTER(4); 

    private int seq; 

    SeasonEnum(int seq) { 

        this.seq = seq; 

    } 

    public int getSeq() { 

        return seq; 

    } 
} 

---

1.3 代码格式

1.【重要】如果大括号内为空，简洁地写成{}即可，大括号中间无需换行和空格；如果是非空代码块，则：

1）左大括号前不换行。

2）左大括号后换行。

3）右大括号前换行。

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

2.【重要】左小括号和右边相邻字符之间不需要空格；右小括号和左边相邻字符之间也不需要空格；而左大 括号前需要加空格。详见第 5 条下方正例提示。

反例：if(空格 a == b 空格)

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

4.【重要】任何二目、三目运算符的左右两边都需要加一个空格。

说明：包括赋值运算符 =、逻辑运算符 &&、加减乘除符号等。

5.【重要】采用 4 个空格缩进，禁止使用 Tab 字符。