编程导航会员会员
登录/注册

《史上最全的 Java 命名规范参考！》

大家好，我是贺同学。


最近几天，打算陆续给星球的小伙伴们，分享一些技术相关的帖子。


星球里大多数是学 Java 的小伙伴们，所以，今天给大家分享一篇（ps：史上最全hh）的 Java 命名规范参考。



0x01 开篇


学习和工作中，我们都希望，自己写出来的代码， 简洁清爽，一目了然，既减少了日后的沟通成本，也提高了后续维护的效率。


相信大家会经常因为起名字而纠结，夸张点可以说是编程 5 分钟，命名 1 小时！导致命名成为了工作中的拦路虎。


其实这背后的原因，每个公司都有不同的标准，目的是为了保持统一，减少沟通成本，提升团队研发效能。


所以本文中，贺哥结合阿里巴巴开发规范，以及工作中的见闻针对 Java 领域相关命名进行整理和总结，仅供参考。



0x02 Java 中的命名规范


好的命名能体现出代码的特征，含义或者是用途，让阅读者可以根据名称的含义快速厘清程序的脉络。


不同语言中采用的命名形式大相径庭，Java 中常用到的命名形式共有三种，既首字母大写的 UpperCamelCase，首字母小写的 lowerCamelCase 以及全部大写的并用下划线分割单词的 UPPER_CAMEL_UNSER_SCORE。通常约定，类一般采用大驼峰命名，方法和局部变量使用小驼峰命名，而大写下划线命名通常是常量和枚举中使用。



0x03 包命名



包名统一使用小写，点分隔符之间有且仅有一个自然语义的英文单词或者多个单词自然连接到一块（如 springframework，deepspace 不需要使用任何分割）。包名统一使用单数形式，如果类命有复数含义，则可以使用复数形式。


包名的构成可以分为以下几四部分【前缀】 【发起者名】【项目名】【模块名】。常见的前缀可以分为以下几种：




0x04 类命名


类名使用大驼峰命名形式，类命通常时名词或名词短语，接口名除了用名词和名词短语以外，还可以使用形容词或形容词短语，如 Cloneable，Callable 等，表示实现该接口的类有某种功能或能力。对于测试类则以它要测试的类开头，以 Test 结尾，如 HashMapTest。


对于一些特殊特有名词缩写也可以使用全大写命名，比如 XMLHttpRequest，不过笔者认为缩写三个字母以内都大写，超过三个字母则按照要给单词算。这个没有标准如阿里巴巴中 fastjson 用 JSONObject 作为类命，而 google 则使用 JsonObjectRequest 命名，对于这种特殊的缩写，原则是统一就好。



0x05 方法命名



方法命名采用小驼峰的形式，首字小写，往后的每个单词首字母都要大写。和类名不同的是，方法命名一般为动词或动词短语，与参数或参数名共同组成动宾短语，即动词 + 名词。一个好的函数名一般能通过名字直接获知该函数实现什么样的功能。


5.1 返回真伪值的方法


注：Prefix-前缀，Suffix-后缀，Alone-单独使用


5.2 用来检查的方法





5.3 按需求才执行的方法




5.4 异步相关方法



5.5 回调方法




5.6 操作对象生命周期的方法


5.7 与集合操作相关的方法



5.8 与数据相关的方法



5.9 成对出现的动词



0x06 变量&常量命名


6.1 变量命名


变量是指在程序运行中可以改变其值的量，包括成员变量和局部变量。变量名由多单词组成时，第一个单词的首字母小写，其后单词的首字母大写，俗称骆驼式命名法（也称驼峰命名法），如 computedValues，index、变量命名时，尽量简短且能清楚的表达变量的作用，命名体现具体的业务含义即可。


变量名不应以下划线或美元符号开头，尽管这在语法上是允许的。变量名应简短且富于描述。变量名的选用应该易于记忆，即，能够指出其用途。尽量避免单个字符的变量名，除非是一次性的临时变量。pojo 中的布尔变量，都不要加 is(数据库中的布尔字段全都要加 is_ 前缀)。


6.2 常量命名



常量命名 CONSTANT_CASE，一般采用全部大写（作为方法参数时除外），单词间用下划线分割。那么什么是常量呢？


常量是在作用域内保持不变的值，一般使用 final 进行修饰。一般分为三种，全局常量（public static final 修饰），类内常量（private static final 修饰）以及局部常量（方法内，或者参数中的常量），局部常量比较特殊，通常采用小驼峰命名即可。


/**
* 一个demo
* @author Tom
* @date 2023-07-07 00:25
**/
publicclass HelloWorld {

/**
* 局部常量(正例)
*/
publicstaticfinallong USER_MESSAGE_CACHE_EXPIRE_TIME = 3600;

/**
* 局部常量(反例，命名不清晰）
*/
publicstaticfinallong MESSAGE_CACHE_TIME = 3600;

/**
* 全局常量
*/
privatestaticfinal String ERROR_MESSAGE = " error message";

/**
* 成员变量
*/
privateint currentUserId;

/**
* 控制台打印 {@code message} 信息
*
* @param message 消息体，局部常量
*/
public void sayHello(final String message){
System.out.println("Hello world!");
}

}

常量一般都有自己的业务含义,不要害怕长度过长而进行省略或者缩写。如，用户消息缓存过期时间的表示，那种方式更佳清晰，交给你来评判。


通用命名规则


  1. 尽量不要使用拼音；杜绝拼音和英文混用。对于一些通用的表示或者难以用英文描述的可以采用拼音，一旦采用拼音就坚决不能和英文混用。正例：BeiJing， HangZhou 反例：validateCanShu
  2. 命名过程中尽量不要出现特殊的字符，常量除外。
  3. 尽量不要和 jdk 或者框架中已存在的类重名，也不能使用 java 中的关键字命名。
  4. 妙用介词，如 for(可以用同音的 4 代替), to(可用同音的 2 代替), from, with，of 等。如类名采用 User4RedisDO，方法名 getUserInfoFromRedis，convertJson2Map 等。



0x07 代码注解


7.1 注解的原则


好的命名增加代码阅读性，代码的命名往往有严格的限制。而注解不同，程序员往往可以自由发挥，单并不意味着可以为所欲为之胡作非为。优雅的注解通常要满足三要素。

  1. Nothing is strange 没有注解的代码对于阅读者非常不友好，哪怕代码写的在清除，阅读者至少从心理上会有抵触，更何况代码中往往有许多复杂的逻辑，所以一定要写注解，不仅要记录代码的逻辑，还有说清楚修改的逻辑。
  2. Less is more 从代码维护角度来讲，代码中的注解一定是精华中的精华。合理清晰的命名能让代码易于理解，对于逻辑简单且命名规范，能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担，更何况大部分都是废话。
// 根据id获取信息【废话注解】
getMessageById(id)
  1. Advance with the time 注解应该随着代码的变动而改变，注解表达的信息要与代码中完全一致。通常情况下修改代码后一定要修改注解。


7.2 注解格式


注解大体上可以分为两种，一种是 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 Tom
* @time 2022/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. 枚举类的各个属性值都要使用注解，枚举可以理解为是常量，通常不会发生改变，通常会被在多个地方引用，对枚举的修改和添加属性通常会带来很大的影响。
  2. 保持排版整洁，不要使用行尾注释；双斜杠和星号之后要用 1 个空格分隔。


id = 1;// 反例：不要使用行尾注释
//反例：换行符与注释之间没有缩进
int age = 18;
// 正例：姓名
String name;
/**
* 1. 多行注释
*
* 2. 对于不同的逻辑说明，可以用空行分隔
*/



0x08 总结


无论是命名和注解，核心目的都是为了让代码和工程师进行对话，增强代码的可读性，可维护性。优秀的代码往往能够见名知意，注解往往是对命名的补充和完善。命名太南了！ 


小伙伴们，你学废了么？😜


#技术 #经验 #Java


参考文献：

《码出高效》

https://www.cnblogs.com/wangcp-2014/p/10215620.html

https://qiita.com/KeithYokoma/items/2193cf79ba76563e3db6

https://google.github.io/styleguide/javaguide.html#s2.1-file-name

Java
0个评论
全部评论
点击登录，快来和大家讨论吧～
表情
图片
暂无评论
程序员贺同学
程序员贺同学
等级vipguest
内容推荐
更多
LEO 卫星星座管理平台
4
新手SpringSecurity6.0源码流程总结
3
🛰️ dtSpaceMap - 实时卫星追踪 3D 可视化平台
5
Spring Boot 如何处理跨域请求（CORS）：深度调研报告
3
#字节内推# 实习、校招、社招均有岗位
4
作者分享
更多
#资源# #分享# 微信读书 得到电子书会员能覆盖很多书，找不到的，可以看下下面两个网站 https://zh.z-library.se/ https://zh.annas-archive.org/
22
#资源，好久没有在星球里给大家分享了，最近半年在忙自己的一个大事情，没怎么冒泡（无辜脸.jpg），趁五一假期的小尾巴，给大家分享一个很牛的知识库网站，包括编程语言、算法与软件架构、Web 与大前端、服务端开发、运维与高可用、云与分布式基础架构、人工智能与深度学习等等。 看界面还有完整的技术 & 产品 & 商业知识体系等知识，大家可以收藏学起来！ https://ng-tech.icu/ #分享# #经验#
46
#职场# #经验# 隔壁星球小伙伴分享的，觉得写得不错，在分享一下给大家 《对职场的十点建议》 假如您的孩子大学毕业，初入社会，只允许您传授10条经验给他，您会说什么?对于很多像我一样农村出来的穷二代，父母面朝黄士背朝天供养我上大学和维持基本的生活已经拼尽全力，很多经验都需要自己付出实际的代价去获取，太昂贵。没有高人指点，自己悟性又一般，希望您能不音赐教。谢谢您的时间 排序不分先后。 第一是要用心。做什么事情都要用心。同样做一件事情，花不花心思，结果差很多。要么不做，要做就用心做好 第二要受得了委屈。工作不是在家里。想干就干，不想干就不干。稍微被说几句就服负气的玻璃心的人不适合工作，还是在家里呆着吧应该也没有什么成就 第三勤奋。天赋都差不多的情况下。比的就是谁更勤奋更努力。整体而言勤奋努力的运气就会更好一点。 第四就是，做杂事。下闲子，有用没用的事情都做做，整天只做有用的事情。也会错过那些现在看没什么用，但以后可能会很有用的事。 第五就是。多见人，什么人都聊聊，见见。机会更多。别一个人呆自己的世界里闷着，总拿自己的世界观去看这个世界。眼界只会越来越小 第六就是学会扛责任，遇到事情别推责任，错了就是错了，别找理由借口。 第七，别耍小聪明，耍滑头，一眼就看出来的聪明都是小聪明，挑肥拣瘦，偷工减料，损公肥私都是小聪明。时间久了，谁是谁，大多数人都一清二楚，没必要装。 第八，!学会辨别好人坏人，然后选择跟好人一起，离开坏人。所谓好坏未必是违法乱纪更多是没责任心，喜欢蹭你便宜，出了事，责任都推给你，好处都自己占的人，有这种领导赶紧离开 第九，尽量选择自己喜欢的行业，每天问问自己，喜欢什么擅长什么，把自己的长处做到极致，扬长避短能事半功倍 第十,做个好人，做个对世界抱有善意的人积极乐观的看待世界。这个世界永远都会存在各种问题，无论你悲观还是绝望，都依然存在乐观，悲观都改变不了世界，但是乐观能让你走的更远。悲观只会被抛弃。别做悲观的人也远离悲观的人。（校长语）
40
职场分享：PDCA 模型
37
#经验# #职场# 《混大厂，如何找到自己的生态位》 这两天前老板来深圳出差，一起吃了饭聊聊天，聊到一个话题，职场生态位， 大家也知道，现在大厂晋升也是越来越卷了，一方面是组织架构庞大，在降本增效的大目标下每个人要多做更多的活，但其实同质化也很严重，另一个方面，晋升考核越来越严格 职场生态位：指自己在职场生态当中所占据的位置，尤其是为关键岗位提供核心价值的位置。只有抢占了职场生态位，我们的地位才会最稳固，职位晋升才能最快，个人能力获得最大的提高。当然了，也能轻而易举地收获最多的Money。 在团队里面，你能解决问题，提供成果，或者能提供通往业务目标的方向/方法/捷径，替别人替组织赢得一个生存空间，在生态位上有自己的护城河，你就占据很大的优势。 举个例子，我们常见的，酒店前台，外卖小哥、快递员等等这类靠出卖苦力，没有特别技术含量的职位，就处于职场生态位的比较低端的位置，而且随时有被取代的可能。 而工程师、医生、律师、财务、高级管理人才等技术工种，这些随着经验积累，越来越值钱的职业，就处于职场上比较高端的生态位。 当然这里没有任何歧视岗位的意思，只是做一个对比，毕竟，几十年的工作经验很难被取代。 如果你已经在职场上抢占了不错的生态位，那么恭喜，把眼下工作好好做，就能提交一份满意的人生成绩单 微信公众号平台 18 年以后新注册的默认都没有留言功能，其实类比任何行业，早就是优势，比如社群，平台，人脉链接，早点抓住机会，抓住生态位，抱住大佬，靠近大佬，早点付费进群，抓住身边大佬的生态位，就比晚来的人占据极大的优势 那么，普通人如何找到自己的生态位？ 《https://wx.zsxq.com/mweb/views/weread/search.html?keyword=精进3》的作者采铜老师说：找到生态位很难，创造生态位却很简单。关键点只有三个字：被需要。  这个点怎么理解，比如说我们组的例子，因为最早和我同级的一个小伙伴呢，他来的最早，他可能大二就开始来这边实习了。 就现在他基本上在组里面工作时间最长的，而且对整个我们这趟业务刚做起来的时候，他是最原始的几个人之一，所以说他现在对整个业务的这个了解熟悉程度，上下游链路，包括和其他团队合作模式都比我们后来的人都要清楚，那么他就能做一个小组长的管理，有带人的经验，这样晋升机会就比别人大很多。 那么说回来，如果说你在一个新团队里面，可能是后面来的人，或者说刚加入不久的。那么如果你要找到自己的生态位的话，有几个建议 首先第一个就是说在这个团队中，你要找到自己熟悉的项目，或者感兴趣的项目，或者说要抢到一个很好的活，然后在这个周期中把这个活做好，做得出色，让领导满意，而且是被领导所关心的问题，把领导关心的问题解决好，自然而然领导就关注到你，机会就多了 另外一个你要就是跟一些合作方去聊，或者说一些历史的一些遗留问题去梳理啊，找到一些解决方案，然后呢把这个事一步步推进去，做一些优化之类的，能够改善我们现在已有系统的性能，这个你也可以做一个就是前期的一个技术积累，去做一个优化的一个方向积累，这样也能形成自己的壁垒。 另外还有就是除了把工作做好，如何把工作成果汇报的好也是一个技能，反正在互联网公司混，能力是一方面，让别人如何看到你的能力，展示出来也是很重要的事情。 先聊这么多，大家加油💪
25
下载 APP