刚发一份在网课上学的Java命名规则,就发现了一份超详细的命名规范,大佬还是大佬啊,请收下我的膝盖。因此作为我在CSDN的第一次转载就给它了。本来想一直自己写的。
以下内容为转载整理而来,文章尾附原文地址。
文章目录
每个公司都有不同的标准,目的是为了保持统一,减少沟通成本,提升团队研发效能。此文是原作者结合阿里巴巴开发规范,以及工作中的见闻针对Java领域相关命名进行整理和总结,仅供参考。
Java中的命名规范
好的命名能体现出代码的特征,含义或者是用途,让阅读者可以根据名称的含义快速厘清程序的脉络。不同语言中采用的命名形式大相径庭,Java中常用到的命名形式共有三种,既首字母大写的UpperCamelCase,首字母小写的lowerCamelCase以及全部大写的并用下划线分割单词的UPPERCAMELUNSER_SCORE。通常约定,类一般采用大驼峰命名,方法和局部变量使用小驼峰命名,而大写下划线命名通常是常量和枚举中使用。
常见命名
类型(名) | 约束 | 例 |
---|---|---|
项目 | 全部小写,多个单词用中划线分隔‘-’ | spring-cloud |
包 | 全部小写 | com.alibaba.fastjson |
类 | 单词首字母大写 | Feature,FieldDeserializer |
变量 | 首字母小写;多个单词组成时,除首个单词,其他单词首字母都要大写 | password,userName |
常量 | 全部大写,多个单词,用‘_’分隔 | CACHEEXPIREDTIME |
方法 | 同变量 | read();getById(Long id) |
包命名
包名统一使用小写,点分隔符之间有且仅有一个自然语义的英文单词或者多个单词自然连接到一块(如 springframework,deepspace不需要使用任何分割)。包名统一使用单数形式,如果类命有复数含义,则可以使用复数形式。
包名的构成可以分为以下几四部分【前缀】 【发起者名】【项目名】【模块名】。常见的前缀可以分为以下几种:
前缀 | 例 | 含义 |
---|---|---|
indi或onem | indi.发起者名.项目名.模块名… | 个体项目,由个人发起,但非自己独自完成。可以公开或私有项目,copyright主要属于发起者。 |
pers | pers.个人名.项目名.模块名… | 个人项目,指个人发起,并独自完成可分享的项目,copyright主要属于个人 |
priv | priv.个人名.项目名.模块名… | 私有项目,指个人发起,独自完成,非公开的私人使用的项目,copyright属于个人 |
team | team.团队名.项目名.模块名… | 团队项目,指由团队发起,并由该团队开发的项目,copyright属于该团队所有 |
顶级域名 | com.公司名.项目名.模块名… | 公司项目,copyright由项目发起的公司所有 |
类命名
类名使用大驼峰命名形式,类命通常时名词或名词短语,接口名除了用名词和名词短语以外,还可以使用形容词或形容词短语,如Cloneable,Callable等,表示实现该接口的类有某种功能或能力。对于测试类则以它要测试的类开头,以Test结尾,如HashMapTest。
对于一些特殊特有名词缩写也可以使用全大写命名,比如XMLHttpRequest,不过作者认为缩写三个字母以内都大写,超过三个字母则按照要给单词算。这个没有标准,如阿里巴巴中fastjson用JSONObject作为类命,而google则使用JsonObjectRequest命名,对于这种特殊的缩写,原则是统一就好。
属性(类) | 约束 | 例 |
---|---|---|
抽象 | Abstract或Base开头 | BaseUserService |
枚举 | Enum作为后缀 | OSType |
工具 | Utils作为后缀 | StringUtils |
异常 | Exception | RuntimeException |
接口实现 | 借口名+Impl | UerServiceImpl |
领域模型相 | /DO/DTO/VO/DAO | 正例:UserDAO;反例:UserDao |
设计模式相关 | Builder,Factory等 | 当使用到设计模式时,要使用对应的设计模式作为后缀如ThreadFactory |
处理特定功能 | Handler,Predicate,Validator | 表示处理器,校验器,断言这些类工厂还有配套的方法名如handler,predicate,validator |
测试 | Test后缀 | UserServiceTest表示用来测试UserService类的 |
MVC分层 | Controller,Service,ServiceImpl,DAO后缀 | UserManageConTroller;UserManageDAO |
方法
方法命名采用小驼峰的形式,首字小写,往后的每个单词首字母都要大写。和类名不同的是,方法命名一般为动词或动词短语,与参数或参数名共同组成动宾短语,即动词 + 名词。一个好的函数名一般能通过名字直接获知该函数实现什么样的功能。
返回真伪值的方法
注:pre- prefix前缀,suf- suffix后缀,alo-alone 单独使用
位置 | 单词 | 意义 | 例 |
---|---|---|---|
pre | is | 对象是否符合期待的状态 | isValid |
pre | can | 对象能否执行所期待的动作 | canRemove |
pre | should | 调用方执行某个命令或方法是好还是不好,应不应该,或者说推荐还是不推荐 | shouldMigrate |
pre | has | 对象是否持有所期待的数据和属性 | hasObservers |
pre | needs | 调用方是否需要执行某个命令或方法 | needsMigrate |
用来检查的方法
单词 | 意义 | 例 |
---|---|---|
ensure | 检查是否为期待的状态,不是则抛出异常或返回error code | enureCapacity |
validate | 检查是否为正确的状态,不是则抛出异常或返回error code | validateInputs |
按需求才执行的方法
位置 | 单词 | 意义 | 例 |
---|---|---|---|
suf | IfNeeded | 需要的时候执行,不需要则什么都不做 | drawIfNeeded |
pre | might | 同上 | mightCrete |
pre | try | 尝试执行,失败时抛出异常或是返回error code | tryCreate |
suf | OrDefault | 尝试执行,失败时返回默认值 | getOrDefault |
suf | OrElse | 尝试执行,失败时返回实际参数中指定的值 | GgetOrElse |
pre | force | 强制尝试执行,error抛出异常或是返回值 | forceCreate,forceStop |
异步相关方法
位置 | 单词 | 意义 | 例 |
---|---|---|---|
pre | blocking | 线程阻塞方法 | blockingGetUser |
suf | Inbackground | 执行在后台线程 | doInBackground |
suf | Asysnc | 异步方法 | sendAsync |
suf | Sync | 同步方法 | sendSync |
pre/alo | schdule | Job和Task放入队列 | schedule,scheduleJob |
pre/alo | post | 同上 | postJob |
回调方法
位置 | 单词 | 意义 | 例 |
---|---|---|---|
pre | on | 事件发生时执行 | onCompleted |
pre | before | 事件发生前执行 | beforeUpdate |
pre | pre | 同上 | preUpdate |
pre | will | 同上 | willUpdate |
pre | after | 事件发生后执行 | afterUpdate |
pre | post | 同上 | postUpdate |
pre | did | 同上 | didUpdate |
pre | should | 确认事件是否可以执行 | shouldUpdate |
操作对象生命周期的方法
单词 | 意义 | 例 |
---|---|---|
initialize | 初始化或延迟初始化使用 | initalize |
pause | 暂停 | onPause,pause |
stop | 停止 | onStop,stop |
abandon | 销毁的替代 | abandon |
destroy | 同上 | destroy |
dispose | 同上 | dispose |
与集合操作相关的方法
单词 | 意义 | 例 |
---|---|---|
contains | 是包含指定对象相同的对象 | contains |
add | 添加 | addJob |
append | 添加 | appendJob |
insert | 插入到下标n | insertJob |
put | 添加与key对应的元素 | putJob |
remove | 移除元素 | removeJob |
enqueue | 添加到队列的最末位 | enqueueJob |
deueue | 从队列中头部取出并移除 | dequeueJob |
push | 添加到栈头 | pushJob |
pop | 从栈头取出并移除 | popJob |
peek | 从栈头取出但不移除 | peekJob |
find | 寻找符合条件的某物 | findById |
与数据相关的方法
单词 | 意义 | 例 |
---|---|---|
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 |
成对出现的动词
单词 | 意义 |
---|---|
get获取 | ste设置 |
add增加 | remove删除 |
create创建 | destory移除 |
start启动 | stop停止 |
open打开 | close关闭 |
read读取 | write写入 |
load载入 | save保存 |
create创建 | destroy销毁 |
begin开始 | end结束 |
backup备份 | restore恢复 |
import导入 | export导出 |
spit分割 | merge合并 |
inject注入 | extract提取 |
attach注入 | 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 | 调试 |
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_ 前缀)。
常量命名
常量命名CONSTANT_CASE,一般采用全部大写(作为方法参数时除外),单词间用下划线分割。
那么什么是常量呢?
常量是在作用域内保持不变的值,一般使用final进行修饰。一般分为三种:
- 全局常量(public static final修饰)
- 类内常量(private static final 修饰)
- 局部常量(方法内,或者参数中的常量)
局部常量比较特殊,通常采用小驼峰命名即可。
public class HelloWorld {
/**
*局部常量(正例)
*/
publlic ststic final long USER_MESSAGE_CACHE_EXPIRE_TIME = 3600;
/**
*局部常量(反例,命名不清晰)
*/
public static final long MESSAGE_CACHE_TIME = 3600;
/**
*全局常量
*/
private static final String ERROR_MESSAGE = "error message";
/**
*成员变量
*/
private int currentUserId;
/**
*控制台打印{@code message}信息
*
*@param message信息体,局部常量
*/
piblic void sayHello(final String message){
System.out.println("Hello World!");
}
}
常量一般都有自己的业务含义,不要害怕长度过长而进行省略或者缩写。如,用户消息缓存过期时间的表示,那种方式更佳清晰,交给你来评判。
通用命名规则
尽量不要使用拼音;杜绝拼音和英文混用。对于一些通用的表示或者难以用英文描述的可以采用拼音,一旦采用拼音就坚决不能和英文混用。正例:BeiJing, HangZhou 反例:validateCanShu
- 命名过程中尽量不要出现特殊的字符,常量除外。
- 尽量不要和jdk或者框架中已存在的类重名,也不能使用java中的关键字命名。
- 妙用介词,如for(可以用同音的数字4代替), to(可用同音的数字2代替), from, with,of等。如类名采用
- User4RedisDO,方法名getUserInfoFromRedis,convertJson2Map等。
代码注解
注解的原则
好的命名增加代码阅读性,代码的命名往往有严格的限制。而注解不同,程序员往往可以自由发挥,单并不意味着可以为所欲为之胡作非为。优雅的注解通常要满足三要素。
- Nothing is strange
没有注解的代码对于阅读者非常不友好,哪怕代码写的在清除,阅读者至少从心理上会有抵触,更何况代码中往往有许多复杂的逻辑,所以一定要写注解,不仅要记录代码的逻辑,还有说清楚修改的逻辑。 - Less is more
从代码维护角度来讲,代码中的注解一定是精华中的精华。合理清晰的命名能让代码易于理解,对于逻辑简单且命名规范,能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担,更何况大部分都是废话。
// 根据id获取信息【废话注解】
- getMessageById(id) Advance with the time
注解应该随着代码的变动而改变,注解表达的信息要与代码中完全一致。通常情况下修改代码后一定要修改注解。
注解格式
注解大体上可以分为两种,一种是javadoc注解,另一种是简单注解。javadoc注解可以生成JavaAPI为外部用户提供有效的支持javadoc注解通常在使用IDEA,或者Eclipse等开发工具时都可以自动生成,也支持自定义的注解模板,仅需要对对应的字段进行解释。参与同一项目开发的同学,尽量设置成相同的注解模板。
包注解
包注解在工作中往往比较特殊,通过包注解可以快速知悉当前包下代码是用来实现哪些功能,强烈建议工作中加上,尤其是对于一些比较复杂的包,包注解一般在包的根目录下,名称统一为package-info.java。
/**
* 落地也质量检测
* 1. 用来解决什么问题
* 对广告主投放的广告落地页进行性能检测,模拟不同的系统,如Android,IOS等; 模拟不同的网络:2G,3G,4G,wifi等
* 2. 如何实现
* 基于chrome浏览器,用chromedriver驱动浏览器,设置对应的网络,OS参数,获取到浏览器返回结果。
* 注意:网络环境配置信息{@link cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常规速度,可以根据实际情况进行调整
* @author cruder
* @time 2019/12/7 20:3 下午
*/package cn.mycookies.landingpagecheck;
类注解
javadoc注解中,每个类都必须有注解。
/**
*Copyringht (c),2019-2020,Jann balabala...
*
*类的介绍:这是一个用来做什么的类,有哪些功能,用到的技术......
*
*@author 类创建者姓名 保持对齐
*@date 创建日期 保持对齐
*@version 版本号 保持对齐
*/
属性注解
在每个属性前面必须加上属性注释,通常有一下两种形式,至于怎么选择,你高兴就好,不过一个项目中要保持统一。
/** 提示信息 */
private String userName;
/**
* 密码
*/
private String password;
方法注释
在每个方法前面必须加上方法注释,对于方法中的每个参数,以及返回值都要有说明。
位置 | 单词 | 意义 | 例 |
---|---|---|---|
pre | blocking | 线程阻塞方法 | blockingGetUser |
suf | InBackground | 执行在后台线程 | doInBackground |
suf | Async | 异步方法 | sendAsync |
suf | Sync | 同步方法 | sendSync |
pre/alo | schedule | Job和Task放入队列 | schedule,scheduleJob |
pre/alo | post | 同上 | postJob |
构造方法注释
在每个构造方法前面必须加上注释,注释模板如下:
/**
* 构造方法的详细说明
*
* @param xxx 参数1的使用说明,能否为null
* @throws 异常类型 注明此类方法中抛出异常的说明
*/
注意事项
而简单注解往往是需要工程师字节定义,在使用注解时应该注意一下几点:
枚举类的各个属性值都要使用注解,枚举可以理解为是常量,通常不会发生改变,通常会被在多个地方引用,对枚举的修改和添加属性通常会带来很大的影响。
保持排版整洁,不要使用行尾注释;双斜杠和星号之后要用1个空格分隔。
int id = 1;// 反例:不要使用行尾注释
// 反例:换行符与注释之间没有缩进
int age = 18;
// 正例:姓名
String name;
/**
* 1.多行注释
*
* 2.对于不同的逻辑说明,可以用空行分隔
*/
用了下午加晚上的时间,这篇转载算是终于敲完了。虽是转载,但仍保证全篇手打。一是对这篇文章很尊敬,二是希望手打加深影响。打完才发现这篇文章居然有8700多字,看完留个赞再走呗。
第一次转载文章,不懂具体有什么要求。若有缺漏之处希望各位能够指出。
此文章仅供学习所用。
原地址:
https://baijiahao.baidu.com/s?id=1654685815662722805&wfr=spider&for=pc