Effective Java(3rd)-Item68 遵守普遍接受的命名约定

  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。
  为了快速参考,下表显示了排版约定的示例


image.png

  语法命名约定比排版约定更灵活,也更有争议。包没有语法命名约定。可实例化的类,包括枚举类型,通常用一个或多个名词短语来命名,例如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开头)才是可接受的,但这种说法几乎没有根据。前两种形式的代码通常可读性更强,例如:


image.png

  以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天

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 205,033评论 6 478
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 87,725评论 2 381
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 151,473评论 0 338
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,846评论 1 277
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,848评论 5 368
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,691评论 1 282
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 38,053评论 3 399
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,700评论 0 258
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 42,856评论 1 300
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,676评论 2 323
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,787评论 1 333
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,430评论 4 321
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 39,034评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,990评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,218评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 45,174评论 2 352
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,526评论 2 343

推荐阅读更多精彩内容