[转载]编码5分钟，命名2小时？史上最全的Java命名规范参考

以下文章来源于公众号&＃xff1a;Java填坑笔记 &＃xff0c;作者李强&＃xff08;推荐关注&＃xff09;

简洁清爽的代码风格应该是大多数工程师所期待的。在工作中笔者常常因为起名字而纠结&＃xff0c;夸张点可以说是编程 5 分钟&＃xff0c;命名两小时&＃xff01;究竟为什么命名成为了工作中的拦路虎。

每个公司都有不同的标准&＃xff0c;目的是为了保持统一&＃xff0c;减少沟通成本&＃xff0c;提升团队研发效能。所以本文中是笔者结合阿里巴巴开发规范&＃xff0c;以及工作中的见闻针对 Java 领域相关命名进行整理和总结&＃xff0c;仅供参考。

一&＃xff0c;Java 中的命名规范

好的命名能体现出代码的特征&＃xff0c;含义或者是用途&＃xff0c;让阅读者可以根据名称的含义快速厘清程序的脉络。不同语言中采用的命名形式大相径庭&＃xff0c;Java 中常用到的命名形式共有三种&＃xff0c;既首字母大写的 UpperCamelCase&＃xff0c;首字母小写的 lowerCamelCase 以及全部大写的并用下划线分割单词的 UPPER_CAMEL_UNSER_SCORE。通常约定&＃xff0c;类一般采用大驼峰命名&＃xff0c;方法和局部变量使用小驼峰命名&＃xff0c;而大写下划线命名通常是常量和枚举中使用。

二&＃xff0c;包命名

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

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

三&＃xff0c;类命名

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

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

四&＃xff0c;方法

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

4.1 返回真伪值的方法

注&＃xff1a;Prefix-前缀&＃xff0c;Suffix-后缀&＃xff0c;Alone-单独使用

4.2 用来检查的方法

4.3 按需求才执行的方法

4.4 异步相关方法

4.5 回调方法

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

4.7 与集合操作相关的方法

4.8 与数据相关的方法

4.9 成对出现的动词

五&＃xff0c;变量&常量命名

5.1 变量命名

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

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

5.2 常量命名

常量命名 CONSTANT_CASE&＃xff0c;一般采用全部大写&＃xff08;作为方法参数时除外&＃xff09;&＃xff0c;单词间用下划线分割。那么什么是常量呢&＃xff1f;

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

/*** 一个demo** &＃64;author Jann Lee* &＃64;date 2019-12-07 00:25**/
public class HelloWorld {/*** 局部常量(正例)*/public static final long USER_MESSAGE_CACHE_EXPIRE_TIME &＃61; 3600;/*** 局部常量(反例&＃xff0c;命名不清晰&＃xff09;*/public static final long MESSAGE_CACHE_TIME &＃61; 3600;/*** 全局常量*/private static final String ERROR_MESSAGE &＃61; " error message";/*** 成员变量*/private int currentUserId;/*** 控制台打印 {&＃64;code message} 信息** &＃64;param message 消息体&＃xff0c;局部常量*/public void sayHello(final String message){System.out.println("Hello world!");}}


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

通用命名规则#

1. 尽量不要使用拼音&＃xff1b;杜绝拼音和英文混用。对于一些通用的表示或者难以用英文描述的可以采用拼音&＃xff0c;一旦采用拼音就坚决不能和英文混用。正例&＃xff1a;BeiJing&＃xff0c; HangZhou 反例&＃xff1a;validateCanShu

2. 命名过程中尽量不要出现特殊的字符&＃xff0c;常量除外。

3. 尽量不要和 jdk 或者框架中已存在的类重名&＃xff0c;也不能使用 java 中的关键字命名。

4. 妙用介词&＃xff0c;如 for(可以用同音的 4 代替), to(可用同音的 2 代替), from, with&＃xff0c;of 等。如类名采用 User4RedisDO&＃xff0c;方法名 getUserInfoFromRedis&＃xff0c;convertJson2Map 等。

六&＃xff0c;代码注解

6.1 注解的原则

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

1. Nothing is strange 没有注解的代码对于阅读者非常不友好&＃xff0c;哪怕代码写的在清除&＃xff0c;阅读者至少从心理上会有抵触&＃xff0c;更何况代码中往往有许多复杂的逻辑&＃xff0c;所以一定要写注解&＃xff0c;不仅要记录代码的逻辑&＃xff0c;还有说清楚修改的逻辑。

2. Less is more 从代码维护角度来讲&＃xff0c;代码中的注解一定是精华中的精华。合理清晰的命名能让代码易于理解&＃xff0c;对于逻辑简单且命名规范&＃xff0c;能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担&＃xff0c;更何况大部分都是废话。

// 根据id获取信息【废话注解】
getMessageById(id)


1. Advance with the time 注解应该随着代码的变动而改变&＃xff0c;注解表达的信息要与代码中完全一致。通常情况下修改代码后一定要修改注解。

6.2 注解格式

注解大体上可以分为两种&＃xff0c;一种是 javadoc 注解&＃xff0c;另一种是简单注解。javadoc 注解可以生成 JavaAPI 为外部用户提供有效的支持 javadoc 注解通常在使用 IDEA&＃xff0c;或者 Eclipse 等开发工具时都可以自动生成&＃xff0c;也支持自定义的注解模板&＃xff0c;仅需要对对应的字段进行解释。参与同一项目开发的同学&＃xff0c;尽量设置成相同的注解模板。

a. 包注解

包注解在工作中往往比较特殊&＃xff0c;通过包注解可以快速知悉当前包下代码是用来实现哪些功能&＃xff0c;强烈建议工作中加上&＃xff0c;尤其是对于一些比较复杂的包&＃xff0c;包注解一般在包的根目录下&＃xff0c;名称统一为 package-info.java。

/*** 落地也质量检测* 1. 用来解决什么问题* 对广告主投放的广告落地页进行性能检测&＃xff0c;模拟不同的系统&＃xff0c;如Android&＃xff0c;IOS等; 模拟不同的网络&＃xff1a;2G&＃xff0c;3G&＃xff0c;4G&＃xff0c;wifi等** 2. 如何实现* 基于chrome浏览器&＃xff0c;用chromedriver驱动浏览器&＃xff0c;设置对应的网络&＃xff0c;OS参数&＃xff0c;获取到浏览器返回结果。** 注意&＃xff1a;网络环境配置信息{&＃64;link cn.myCOOKIEs.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常规速度&＃xff0c;可以根据实际情况进行调整** &＃64;author cruder* &＃64;time 2019/12/7 20:3 下午*/
package cn.myCOOKIEs.landingpagecheck;


b. 类注接

javadoc 注解中&＃xff0c;每个类都必须有注解。

/**
* Copyright (C), 2019-2020, Jann balabala...
*
* 类的介绍&＃xff1a;这是一个用来做什么事情的类&＃xff0c;有哪些功能&＃xff0c;用到的技术.....
*
* &＃64;author 类创建者姓名 保持对齐
* &＃64;date 创建日期 保持对齐
* &＃64;version 版本号 保持对齐
*/


c. 属性注解

在每个属性前面必须加上属性注释&＃xff0c;通常有一下两种形式&＃xff0c;至于怎么选择&＃xff0c;你高兴就好&＃xff0c;不过一个项目中要保持统一。

/** 提示信息 */
private String userName;
/*** 密码*/
private String password;


d. 方法注释

在每个方法前面必须加上方法注释&＃xff0c;对于方法中的每个参数&＃xff0c;以及返回值都要有说明。

/*** 方法的详细说明&＃xff0c;能干嘛&＃xff0c;怎么实现的&＃xff0c;注意事项...** &＃64;param xxx 参数1的使用说明&＃xff0c; 能否为null* &＃64;return 返回结果的说明&＃xff0c; 不同情况下会返回怎样的结果* &＃64;throws 异常类型 注明从此类方法中抛出异常的说明*/


e. 构造方法注释

在每个构造方法前面必须加上注释&＃xff0c;注释模板如下&＃xff1a;

/*** 构造方法的详细说明** &＃64;param xxx 参数1的使用说明&＃xff0c; 能否为null* &＃64;throws 异常类型 注明从此类方法中抛出异常的说明*/


而简单注解往往是需要工程师字节定义&＃xff0c;在使用注解时应该注意一下几点&＃xff1a;

1. 枚举类的各个属性值都要使用注解&＃xff0c;枚举可以理解为是常量&＃xff0c;通常不会发生改变&＃xff0c;通常会被在多个地方引用&＃xff0c;对枚举的修改和添加属性通常会带来很大的影响。

2. 保持排版整洁&＃xff0c;不要使用行尾注释&＃xff1b;双斜杠和星号之后要用 1 个空格分隔。

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

总结

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

参考文献&＃xff1a;

《码出高效》

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