阿里开发手册 嵩山版-编程规约 (二)常量定义

简介: 《阿里开发手册 嵩山版》是阿里巴巴集团技术团队的集体智慧结晶,旨在通过编程规约、异常日志、单元测试等多个维度的规范,提升Java开发者的编码效率和质量,确保软件的稳定性和安全性。本篇为编程规约 (二)常量定义。

历史版本

前言

《Java 开发手册》是阿里巴巴集团技术团队的集体智慧结晶和经验总结,经历了多次大规模一线实战的检验及不断完善,公开到业界后,众多社区开发者踊跃参与,共同打磨完善,系统化地整理成册,当前的版本是嵩山版。现代软件行业的高速发展对开发者的综合素质要求越来越高,因为不仅是编程知识点,其它维度的知识点也会影响到软件的最终交付质量。比如:五花八门的错误码人为地增加排查问题的难度;数据库的表结构和索引设计缺陷带来的系统架构缺陷或性能风险;工程结构混乱导致后续项目维护艰难;没有鉴权的漏洞代码易被黑客攻击等等。所以本手册以 Java 开发者为中心视角,划分为编程规约、异常日志、单元测试、安全规约、MySQL 数据库、工程结构、设计规约七个维度,再根据内容特征,细分成若干二级子目录。

另外,依据约束力强弱及故障敏感性,规约依次分为【强制】【推荐】、___【参考】三大类。在延伸信息中,“说明___”对规约做了适当扩展和解释;“正例”提倡什么样的编码和实现方式;“反例”说明需要提防的雷区,以及真实的错误案例。

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

我们已经在 2017 杭州云栖大会上发布了配套的 Java 开发规约 IDE 插件,下载量达到 162 万人次,阿里云效也集成了代码规约扫描引擎。次年,发布 36 万字的配套详解图书《码出高效》,本书秉持“图胜于表,表胜于言”的理念,深入浅出地将计算机基础、面向对象思想、JVM 探源、数据结构与集合、并发与多线程、单元测试等知识客观、立体地呈现出来。紧扣学以致用、学以精进的目标,结合阿里巴巴实践经验和故障案例,与底层源码解析融会贯通,娓娓道来。《码出高效》和《Java开发手册》稿费所得收入均捐赠公益事情,希望用技术情怀帮助更多的人。

💡

编程规约

(二)常量定义

1. 【强制】不允许任何魔法值(即未经预先定义的常量)直接出现在代码中。

反例:

// 本例中,开发者 A 定义了缓存的 key,然后开发者 B 使用缓存时少了下划线,即 key 是"Id#taobao"+tradeId,导致出现故障

String key = "Id#taobao_" + tradeId;

cache.put(key, value);

2. 【强制】在 long 或者 Long 赋值时,数值后使用大写字母 L,不能是小写字母 l,小写容易跟数字混淆,造成误解。

说明:Long a = 2l; 写的是数字的 21,还是 Long 型的 2?

3. 【推荐】不要使用一个常量类维护所有常量,要按常量功能进行归类,分开维护。

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

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

4. 【推荐】常量的复用层次有五层:跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。

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

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

反例:易懂变量也要统一定义成应用内共享常量,两位工程师在两个类中分别定义了“YES”的变量:

类 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 定义

5. 【推荐】(有点没懂)如果变量值仅在一个固定范围内变化用 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;
     } 
}
相关文章
|
Java 程序员 数据库
黄山归来不看岳:《Java开发手册(黄山版)》新增 11 条规约
黄山归来不看岳:《Java开发手册(黄山版)》新增 11 条规约
黄山归来不看岳:《Java开发手册(黄山版)》新增 11 条规约
|
小程序 JavaScript Java
【资料】阿里Java开发手册
本文是关于分享阿里Java开发手册资源及促进编程规范学习的指南。作者以个人经历引入,讲述了公司领导通过细致讲解阿里Java开发手册,提升了团队对代码质量和编程规范的认识
1640 0
【资料】阿里Java开发手册
|
设计模式 移动开发 Java
【阿里规约】阿里开发手册解读——代码格式篇
本文所有代码格式规范遵循《阿里规约》,从编码、换行符、空格规则、括号规则、字符数等方面展开,详细阐述方法参数、强制转换、运算符、缩进等元素的编写规范。
【阿里规约】阿里开发手册解读——代码格式篇
|
设计模式 安全 Java
阿里开发手册 嵩山版-编程规约 (一)命名规范
该文章主要介绍了阿里开发手册嵩山版中关于编程规约的命名规范,包括代码命名的强制和推荐规定,以及接口、类、枚举等的命名规则和各层命名规约等内容。
 阿里开发手册 嵩山版-编程规约 (一)命名规范
|
JSON 缓存 前端开发
阿里开发手册 嵩山版-编程规约 (十) 前后端规约
《阿里开发手册 嵩山版》中关于前后端规约的部分,涵盖了前后端交互的API设计、数据格式、错误处理、安全性等关键编程规约,目的是确保前后端开发高效协同,提升软件交付质量。
 阿里开发手册 嵩山版-编程规约 (十) 前后端规约
电子书阅读分享《Java开发手册(嵩山版)》
电子书阅读分享《Java开发手册(嵩山版)》
|
设计模式 Java 关系型数据库
【阿里规约】阿里开发手册解读——命名规范篇
本文中所有代码命名规范遵循《阿里规约》,从包名、类名、变量名等角度展开,详细阐述测试类、枚举类、数组、布尔型变量、方法等元素的命名规范。
【阿里规约】阿里开发手册解读——命名规范篇
|
存储 关系型数据库 MySQL
【阿里规约】阿里开发手册解读——数据库和ORM篇
从命名规范、建表规范、查询规范、索引规范、操作规范等角度出发,详细阐述MySQL数据库使用过程中所需要遵循的各种规范。
【阿里规约】阿里开发手册解读——数据库和ORM篇
|
存储 设计模式 Java
阿里官方代码规范
这篇文章详细介绍了阿里巴巴官方的代码规范,包括命名规则、常量使用、方法覆写、并发处理、注释规范、数据库设计等多个方面,旨在提高代码的可读性、维护性和扩展性。
|
IDE 安全 Java
阿里开发手册 嵩山版-编程规约 (三)代码格式
《阿里开发手册 嵩山版》的编程规约部分详细介绍了代码格式规范,包括括号使用、空格、注释、行数限制等,旨在提高代码的可读性和维护性。