Java 命名格式规范
Java 命名格式规范
概述
简洁清爽的代码风格应该是大多数开发工程师所期待的。在编码过程中笔者常常因为起名字而纠结，夸张点可以说是编程 5 分钟，命名两小时！究竟为什么命名成为了编码中的拦路虎。
每个公司都有不同的标准，目的是为了保持统一，减少沟通成本，提升团队研发效能。所以本文中是笔者结合阿里巴巴开发规范，以及编码中的见闻针对 Java 领域相关命名进行整理和总结，仅供学习以及参考。
为什么需要重视命名
先搞懂为什么要重视编程中的命名这一行为，它对于我们的编码工作有着什么意义。
好的命名即是注释，别人一看到你的命名就知道你的变量、方法或者类是做什么的！
《Clean Code》这本书中明确指出：
好的代码本身就是注释，我们要尽量规范和美化自己的代码来减少不必要的注释。
若编程语言足够有表达力，就不需要注释，尽量通过代码来阐述。
命名规范介绍
驼峰命名法（CamelCase）
这种命名方式使用大小写混合的格式来区别各个单词，并且单词之间不使用空格隔开或者连接字符连接的命名方式。
大驼峰命名法（UpperCamelCase）
Java中的类名需要使用大驼峰命名法。
小驼峰命名法（lowerCamelCase）
Java中的方法名、参数名、成员变量、局部变量需要使用小驼峰命名法。
蛇形命名法（snake_case）
测试方法名、常量、枚举名称需要使用蛇形命名法。
@Test
void should_get_200_status_code_when_request_is_valid() {
......
}
@Test
void shouldGet200StatusCodeWhenRequestIsValid() {
......
}
串式命名法（kebab-case）
在串式命名法中，各个单词之间通过连接符“-”连接，比如dubbo-registry。
建议项目文件夹名称使用串式命名法（kebab-case），比如spring cloud alibaba中的命名格式
命名易读性规范
1、为了能让命名更加易懂和易读，尽量不要缩写/简写单词，除非这些单词已经被公认可以被这样缩写/简写。比如 CustomThreadFactory 不可以被写成 CustomTF 。
2、命名不像函数一样要尽量追求短，可读性强的名字优先于简短的名字，虽然可读性强的名字会比较长一点。 这个对应我们上面说的第 1 点。
3、避免无意义的命名，你起的每一个名字都要能表明意思。
正例：UserService userService; int userCount;
反例: UserService service; int count
4、避免命名过长（50 个字符以内最好），过长的命名难以阅读并且丑陋。
5、不要使用拼音，更不要使用中文。 不过像 alibaba 、wuhan、taobao 这种国际通用名词可以当做英文来看待。
Java 命名规范
好的命名能体现出代码的特征，含义乃至是用途，让读者可以根据名称的含义快速梳理清楚程序的脉络。不同语言中采用的命名形式大相径庭，Java 中常用到的命名形式共有三种，既首字母大写的 UpperCamelCase（大驼峰），首字母小写的 lowerCamelCase（小驼峰） 以及全部大写的并用下划线分割单词的UPPER_CAMEL_UNSER_SCORE。
通常约定，类一般采用大驼峰命名，方法和局部变量使用小驼峰命名，而大写下划线命名通常是常量和枚举中使用
| 类型 | 约束 | 例 |
|---|---|---|
| 项目名 | 全部小写，多个单词用中划线分隔‘-’ | spring-cloud |
| 包名 | 全部小写 | com.alibaba.fastjson |
| 类名 | 单词首字母大写 | Feature, ParserConfig,DefaultFieldDeserializer |
| 变量名 | 首字母小写，多个单词组成时，除首个单词，其他单词首字母都要大写 | password, userName |
| 常量名 | 全部大写，多个单词，用’_'分隔 | CACHE_EXPIRED_TIME |
| 方法 | 同变量 | read(), readObject(), getById() |
类命名
类名使用大驼峰命名形式，类命通常是名词或名词短语，接口名除了用名词和名词短语以外，还可以使用形容词或形容词短语，如 Cloneable，Callable 等，表示实现该接口的类有某种功能或能力。对于测试类则以它要测试的类开头，以 Test 结尾，如 HashMapTest。
对于一些特有名词缩写也可以使用全大写命名，比如 XMLHttpRequest，不过笔者认为缩写三个字母以内都大写，超过三个字母则按照单词算。这个没有标准如阿里巴巴中 fastjson 用 JSONObject 作为类命，而 google 则使用 JsonObjectRequest 命名，对于这种特殊的缩写，原则是统一就好。
| 属性 | 约束 | 例 |
|---|---|---|
| 抽象类 | Abstract 或者 Base 开头 | BaseUserService / AbstractBeanFactory |
| 枚举类 | Enum 作为后缀 | GenderEnum |
| 工具类 | Utils 作为后缀 | StringUtils |
| 异常类 | Exception 结尾 | RuntimeException |
| 接口实现类 | 接口名+ Impl | UserServiceImpl |
| 领域模型相关 | /DO/DTO/VO/DAO | 正例：UserDAO 反例：UserDo， UserDao |
| 设计模式相关类 | Builder，Factory 等 | 当使用到设计模式时，需要使用对应的设计模式作为后缀，如 ThreadFactory |
| 处理特定功能的 | Handler，Predicate, Validator | 表示处理器，校验器，断言，这些类工厂还有配套的方法名如 handle，predicate，validate |
| 测试类 | Test 结尾 | UserServiceTest， 表示用来测试 UserService 类的 |
| MVC 架构 | Controller，Service，ServiceImpl，DAO 后缀 | UserManageController，UserManageDAO |
方法
方法命名采用小驼峰的形式，首字小写，往后的每个单词首字母都要大写。和类名不同的是，方法命名一般为动词或动词短语，与参数或参数名共同组成动宾短语，即动词 + 名词。一个好的函数名一般能通过名字直接获知该函数实现什么样的功能。
1 返回真伪值的方法
注：Prefix-前缀，Suffix-后缀，Alone-单独使用
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Prefix（前缀） | is | 对象是否符合期待的状态 | isValid |
| Prefix | can | 对象能否执行所期待的动作 | canRemove |
| Prefix | should | 调用方执行某个命令或方法是好还是不好,应不应该，或者说推荐还是不推荐 | shouldMigrate |
| Prefix | has | 对象是否持有所期待的数据和属性 | hasObservers |
| Prefix | needs | 调用方是否需要执行某个命令或方法 | needsMigrate |
2 用来检查的方法
| 单词 | 意义 | 例 |
|---|---|---|
| ensure | 检查是否为期待的状态，不是则抛出异常或返回 error code | ensureCapacity |
| validate | 检查是否为正确的状态，不是则抛出异常或返回 error code | validateInputs |
3 按需求才执行的方法
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Suffix（后缀） | IfNeeded | 需要的时候执行，不需要的时候什么都不做 | drawIfNeeded |
| Prefix | might | 同上 | mightCreate |
| Prefix | try | 尝试执行，失败时抛出异常或是返回 errorcode | tryCreate |
| Suffix | OrDefault | 尝试执行，失败时返回默认值 | getOrDefault |
| Suffix | OrElse | 尝试执行、失败时返回实际参数中指定的值 | getOrElse |
| Prefix | force | 强制尝试执行。error 抛出异常或是返回值 | forceCreate, forceStop |
4 异步相关方法
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Prefix | blocking | 线程阻塞方法 | blockingGetUser |
| Suffix | InBackground | 执行在后台的线程 | doInBackground |
| Suffix | Async | 异步方法 | sendAsync |
| Suffix | Sync | 对应已有异步方法的同步方法 | sendSync |
| Prefix or Alone | schedule | Job 和 Task 放入队列 | schedule, scheduleJob |
| Prefix or Alone | post | 同上 | postJob |
| Prefix or Alone | execute | 执行异步方法（注：我一般拿这个做同步方法名） | execute, executeTask |
| Prefix or Alone | start | 同上 | start, startJob |
| Prefix or Alone | cancel | 停止异步方法 | cancel, cancelJob |
| Prefix or Alone | stop | 同上 | stop, stopJob |
5 回调方法
| 位置 | 单词 | 意义 | 例 |
|---|---|---|---|
| Prefix | on | 事件发生时执行 | onCompleted |
| Prefix | before | 事件发生前执行 | beforeUpdate |
| Prefix | pre | 同上 | preUpdate |
| Prefix | will | 同上 | willUpdate |
| Prefix | after | 事件发生后执行 | afterUpdate |
| Prefix | post | 同上 | postUpdate |
| Prefix | did | 同上 | didUpdate |
| Prefix | should | 确认事件是否可以发生时执行 | shouldUpdate |
6 操作对象生命周期的方法
| 单词 | 意义 | 例 |
|---|---|---|
| initialize | 初始化。也可作为延迟初始化使用 | initialize |
| pause | 暂停 | onPause ，pause |
| stop | 停止 | onStop，stop |
| abandon | 销毁的替代 | abandon |
| destroy | 同上 | destroy |
| dispose | 同上 | dispose |
7 与集合操作相关的方法
| 单词 | 意义 | 例 |
|---|---|---|
| contains | 是否持有与指定对象相同的对象 | contains |
| add | 添加 | addJob |
| append | 添加 | appendJob |
| insert | 插入到下标 n | insertJob |
| put | 添加与 key 对应的元素 | putJob |
| remove | 移除元素 | removeJob |
| enqueue | 添加到队列的最末位 | enqueueJob |
| dequeue | 从队列中头部取出并移除 | dequeueJob |
| push | 添加到栈头 | pushJob |
| pop | 从栈头取出并移除 | popJob |
| peek | 从栈头取出但不移除 | peekJob |
| find | 寻找符合条件的某物 | findById |
8 与数据相关的方法
| 单词 | 意义 | 例 |
|---|---|---|
| create | 新创建 | createAccount |
| new | 新创建 | newAccount |
| from | 从既有的某物新建，或是从其他的数据新建 | fromConfig |
| to | 转换 | toString |
| update | 更新既有某物 | updateAccount |
| load | 读取 | loadAccount |
| fetch | 远程读取 | fetchAccount |
| delete | 删除 | deleteAccount |
| remove | 删除 | removeAccount |
| save | 保存 | saveAccount |
| store | 保存 | storeAccount |
| commit | 保存 | commitChange |
| apply | 保存或应用 | applyChange |
| clear | 清除数据或是恢复到初始状态 | clearAll |
| reset | 清除数据或是恢复到初始状态 | resetAll |
9 成对出现的动词
| 单词 | 意义 |
|---|---|
| get 获取 | set 设置 |
| add 增加 | remove 删除 |
| create 创建 | destory 移除 |
| start 启动 | stop 停止 |
| open 打开 | close 关闭 |
| read 读取 | write 写入 |
| load 载入 | save 保存 |
| create 创建 | destroy 销毁 |
| begin 开始 | end 结束 |
| backup 备份 | restore 恢复 |
| import 导入 | export 导出 |
| split 分割 | merge 合并 |
| inject 注入 | extract 提取 |
| attach 附着 | detach 脱离 |
| bind 绑定 | separate 分离 |
| view 查看 | browse 浏览 |
| edit 编辑 | modify 修改 |
| select 选取 | mark 标记 |
| copy 复制 | paste 粘贴 |
| undo 撤销 | redo 重做 |
| insert 插入 | delete 移除 |
| add 加入 | append 添加 |
| clean 清理 | clear 清除 |
| index 索引 | sort 排序 |
| find 查找 | search 搜索 |
| increase 增加 | decrease 减少 |
| play 播放 | pause 暂停 |
| launch 启动 | run 运行 |
| compile 编译 | execute 执行 |
| debug 调试 | trace 跟踪 |
| observe 观察 | listen 监听 |
| build 构建 | publish 发布 |
| input 输入 | output 输出 |
| encode 编码 | decode 解码 |
| encrypt 加密 | decrypt 解密 |
| compress 压缩 | decompress 解压缩 |
| pack 打包 | unpack 解包 |
| parse 解析 | emit 生成 |
| connect 连接 | disconnect 断开 |
| send 发送 | receive 接收 |
| download 下载 | upload 上传 |
| refresh 刷新 | synchronize 同步 |
| update 更新 | revert 复原 |
| lock 锁定 | unlock 解锁 |
| check out 签出 | check in 签入 |
| submit 提交 | commit 交付 |
| push 推 | pull 拉 |
| expand 展开 | collapse 折叠 |
| begin 起始 | end 结束 |
| start 开始 | finish 完成 |
| enter 进入 | exit 退出 |
| abort 放弃 | quit 离开 |
| obsolete 废弃 | depreciate 废旧 |
| collect 收集 | aggregate 聚集 |
变量名
变量是指在程序运行中可以改变其值的量，包括成员变量和局部变量。变量名由多单词组成时，第一个单词的首字母小写，其后单词的首字母大写，俗称骆驼式命名法（也称驼峰命名法），如 computedValues，index、变量命名时，尽量简短且能清楚的表达变量的作用，命名体现具体的业务含义即可。
变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。pojo 中的布尔变量，都不要加 is(，避免出现序列化问题，数据库中的布尔字段全都要加 is_ 前缀)。
代码注解
注解原则
好的命名能够增加代码阅读性，代码的命名往往有严格的限制。
但是注解不同，程序员往往可以自由发挥，但是这并不意味着可以为所欲为书写注解。优雅的注解通常要满足三要素。
-
Nothing is strange **没有注解的代码对于阅读者非常不友好。**哪怕代码写的在清楚，阅读者至少从心理上会有抵触，更何况代码中往往有许多复杂的逻辑，所以一定要写注解，不仅要记录代码的逻辑，还有说清楚修改的逻辑。
-
Less is more **从代码维护角度来讲，代码中的注解一定是精华中的精华。**合理清晰的命名能让代码易于理解，对于逻辑简单且命名规范，能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担，更何况大部分都是废话。
// 根据id获取信息【废话注解】 getMessageById(id -
Advance with the time **注解应该随着代码的变动而改变。**注解表达的信息要与代码中完全一致。通常情况下修改代码后一定要修改注解。
注解格式
注解大体上可以分为两种，一种是 javadoc 注解，另一种是简单注解。javadoc 注解可以生成 JavaAPI 为外部用户提供有效的支持。 javadoc 注解通常在使用 IDEA，或者 Eclipse 等开发工具时都可以自动生成，也支持自定义的注解模板，仅需要对对应的字段进行解释。参与同一项目开发的同学，尽量设置成相同的注解模板。
a. 包注解
包注解在工作中往往比较特殊，通过包注解可以快速知悉当前包下代码是用来实现哪些功能，强烈建议工作中加上，尤其是对于一些比较复杂的包，包注解一般在包的根目录下，名称统一为 package-info.java。
/**
* 落地质量检测
* 1. 用来解决什么问题
* 对广告主投放的广告落地页进行性能检测，模拟不同的系统，如Android，IOS等; 模拟不同的网络：2G，3G，4G，wifi等
*
* 2. 如何实现
* 基于chrome浏览器，用chromedriver驱动浏览器，设置对应的网络，OS参数，获取到浏览器返回结果。
*
* 注意：网络环境配置信息{@link cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常规速度，可以根据实际情况进行调整
*
* @author coder
* @time 2019/12/7 20:3 下午
*/
package cn.mycookies.landingpagecheck;
b. 类注接
javadoc 注解中，每个类都必须有注解。
/**
* Copyright (C), 2019-2020, Jann balabala...
*
* 类的介绍：这是一个用来做什么事情的类，有哪些功能，用到的技术.....
*
* @author 类创建者姓名 保持对齐
* @date 创建日期 保持对齐
* @version 版本号 保持对齐
*/
c. 属性注解
在每个属性前面必须加上属性注释，通常有一下两种形式，至于怎么选择，你高兴就好，不过一个项目中要保持统一。
/** 提示信息 */
private String userName;
/**
* 密码
*/
private String password;
d. 方法注释
在每个方法前面必须加上方法注释，对于方法中的每个参数，以及返回值都要有说明。
/**
* 方法的详细说明，能干嘛，怎么实现的，注意事项...
*
* @param xxx 参数1的使用说明， 能否为null
* @return 返回结果的说明， 不同情况下会返回怎样的结果
* @throws 异常类型 注明从此类方法中抛出异常的说明
*/
e. 构造方法注释
在每个构造方法前面必须加上注释，注释模板如下：
/**
* 构造方法的详细说明
*
* @param xxx 参数1的使用说明， 能否为null
* @throws 异常类型 注明从此类方法中抛出异常的说明
*/
而简单注解往往是需要工程师自己定义，在使用注解时应该注意一下几点：
- 枚举类的各个属性值都要使用注解，枚举可以理解为是常量，通常不会发生改变，通常会被在多个地方引用，对枚举的修改和添加属性通常会带来很大的影响。
- 保持排版整洁，不要使用行尾注释；双斜杠和星号之后要用 1 个空格分隔。
id = 1;// 反例：不要使用行尾注释
//反例：换行符与注释之间没有缩进
int age = 18;
// 正例：姓名
String name;
/**
* 1. 多行注释
*
* 2. 对于不同的逻辑说明，可以用空行分隔
*/