Java平台有一组完善的命名约定,其中许多约定包含在Java语言规范[JLS, 6.1]中。松散地说,命名约定分为两类:排版和语法。
只有少量的排版命名约定,包括包、类、接口、方法、字段和类型变量。你不应该违反它们,而且没有很好的理由。如果API违反了这些约定,那么它可能很难使用。如果实现违反了这些规则,可能很难维护。:在这两种情况下,违规都有可能使其他使用代码的程序员感到困惑和恼怒,并可能导致错误的假设,从而导致错误。本项目概述了各项公约。
包名和模块名应该是分层的,组件之间用句点分隔。组件应该由小写字母组成,很少有数字。任何将在您的组织外部使用的包的名称都应该以您的组织的Internet域名开头,并将组件颠倒过来,比如 edu.cmu, com.google, org.eff. 以java和javax开头的标准库和可选包是这个规则的例外。用户不能创建名称以java或javax开头的包或模块。将Internet域名转换为包名前缀的详细规则可以在JLS [JLS, 6.1]中找到。
包名的其余部分应该由描述包的一个或多个组件组成。组件应该很短,通常为8个或更少的字符。鼓励使用有意义的缩写,比如,util比utilities要好。缩写词是可以接受的,例如awt。组件通常应该由一个单词或缩写组成。
除了Internet域名之外,许多包的名称只有一个组件。附加组件适用于大型设施,这些设施的大小要求将其分解为非正式的层次结构。例如javax.util包具有丰富的包层次结构,包的名称如java.util.concurrent.atomic。这样的包称为子包,尽管几乎不支持包层次结构。
类和接口名称,包括枚举和注释类型名称,应该由一个或多个单词组成,每个单词的首字母大写,例如List或FutureTask。除了缩略语和某些常见的缩略语如max和min外,应避免使用缩略语。首字母缩略词应该是大写的,还是只有首字母大写,这一点存在一些分歧。虽然有些程序员仍然使用大写,但这是一个强有力的论据只把第一个字母大写:即使连续出现多个首字母缩写,你仍然可以知道一个单词从哪里开始,下一个单词从哪里结束。希望看到哪个类名,HTTPURL还是HTTPURL ?
方法和字段名遵循与类和接口名相同的排版约定,只是方法或字段名的第一个字母应该是小写的,例如 remove或ensureCapacity.如果方法或字段名的首字母缩写出现在第一个单词中,那么它应该是小写的。
前面规则的唯一例外是“常量字段”,它的名称应该由一个或多个大写单词组成,由下划线分隔,例如VALUES或NEGATIVE_INFINITY。常量字段是一个静态的final字段,其值是不可变的。如果静态final字段具有基本类型或不可变引用类型(item17 ),那么它就是常量字段。例如,枚举常量是常量字段。如果静态final字段有一个可变的引用类型,那么如果所引用的对象是不可变的,那么它仍然可以是一个常量字段。注意,常量字段是唯一推荐的下划线用法。
局部变量名与成员名具有类似的排版命名约定,但允许使用缩写,也允许使用单个字符和短字符序列,它们的含义取决于它们出现的上下文,例如i、denom、houseNum.输入参数是一种特殊的局部变量。它们的命名应该比普通的局部变量谨慎得多,因为它们的名称是方法文档的组成部分。
类型参数名通常由单个字母组成。最常见的有以下五种:T表示任意类型,E表示集合的元素类型,K和V表示映射的键和值类型,X表示异常。函数的返回类型通常是R。任意类型的序列可以是T、U、V或T1、T2、T3。
为了快速参考,下表显示了排版约定的示例
语法命名约定比排版约定更灵活,也更有争议。包没有语法命名约定。可实例化的类,包括枚举类型,通常用一个或多个名词短语来命名,例如Thread、PriorityQueue或 ChessPiece。不可实例化的实用程序类( item4 )通常使用复数名词来命名,例如collectors或Collections。接口的名称类似于类,例如Collection或Comparator,或者以able或ible结尾的形容词,例如Runnable、Iterable或Accessible。因为注解类型有如此多的用途,所以没有哪部分语言占主导地位。名词、动词、介词和形容词都很常见,例如,BindingAnnotation, Inject、Inject或Inject。
执行某些操作的方法通常用动词或动词短语(包括对象)命名,例如,append或drawImage。返回布尔值的方法的名称通常以单词is或has开头,后面跟一个名词、一个名词短语,或者任何用作形容词的单词或短语,例如isDigit、isProbablePrime、isEmpty、isEnabled或hasSiblings。
返回被调用对象的非布尔函数或属性的方法通常使用以get开头的名词、名词短语或动词短语来命名,例如size、hashCode或getTime。有一种说法是,只有第三种形式(以get开头)才是可接受的,但这种说法几乎没有根据。前两种形式的代码通常可读性更强,例如:
以get开头的表单起源于基本过时的Java bean规范,该规范构成了早期可重用组件体系结构的基础。有一些现代工具仍然依赖于bean命名约定,您应该可以在任何与这些工具一起使用的代码中随意使用它。如果类同时包含相同属性的setter和getter,则遵循这种命名约定也有很好的先例。在本例中,这两个方法通常被命名为getAttribute和setAttribute。
一些方法名称值得特别注意。转换对象类型(返回不同类型的独立对象)的实例方法通常称为toType,例如toString或toArray。返回视图的方法( item6 )其类型与接收对象类型不同叫做asType,比如asList。返回与调用它们的对象具有相同值的原语的方法通常称为类型值,例如intValue。静态工厂的常见名称包括from、of、valueOf、instance、getInstance、newInstance、getType和newType(第1项,第9页)。
字段名的语法约定没有类、接口和方法名的语法约定建立得好,也不那么重要,因为它们设计得很好api几乎不包含任何公开的字段。类型为boolean的字段通常命名为boolean访问器方法,省略了初始值,比如initialized,initialized。其他类型的字段通常用名词或名词短语来命名,例如height,height或height。局部变量的语法约定类似于字段的语法约定,但更弱。
总之,将标准命名约定内在化,并将其作为第二天性来使用。排版习惯是直接的,而且在很大程度上是明确的;语法惯例更加复杂和松散。引用Java语言规范[JLS, 6.1]中的话说,“如果长期以来的传统用法不这样做,就不应该盲目地遵循这些约定。”
使用常识。
本文写于2019.7.20,历时1天