Google 出品的 Java 编码规范,强烈推荐,既权威又科学

这份文档是 Google Java 编程气概规范的完整界说。当且仅当一个Java源文件相符此文档中的规则, 我们才以为它相符Google的Java编程气概。原文:google.github.io/styleguide/javaguide.html 译者:Hawstein 泉源:hawstein.com/2014/01/20/google-java-style/

与其它的编程气概指南一样,这里所讨论的不仅仅是编码花样美不美观的问题, 同时也讨论一些约定及编码尺度。然而,这份文档主要侧重于我们所普遍遵照的规则, 对于那些不是明确强制要求的,我们只管制止提供意见。

在逆锋起笔微信民众号后台回复关键字:规范,可获取高清 PDF 版的下载地址《Google Java编程气概指南/规范》

Google 出品的 Java 编码规范,强烈推荐,既权威又科学

若是你想获取阿里巴巴最新的《Java开发手册》,请关注逆锋起笔微信民众号,在后台回复关键字:java手册,既可获取。

1.1 术语说明

在本文档中,除非尚有说明:

1、术语class可示意一个通俗类,枚举类,接口或是annotation类型( @interface)

2、术语comment只用来指代实现的注释(implementation comments),我们不使用“documentation comments”一词,而是用Javadoc。

其他的术语说明会偶然在后面的文档泛起。

1.2 指南说明

本文档中的示例代码并不作为规范。也就是说,虽然示例代码是遵照Google编程气概,但并不意味着这是展现这些代码的唯一方式。示例中的花样选择不应该被强制定为规则。

源文件基础

2.1 文件名

源文件以其最顶层的类名来命名,大小写敏感,文件扩展名为 .java。

2.2 文件编码:UTF-8

源文件编码花样为UTF-8。

2.3 特殊字符

2.3.1 空缺字符

除了行竣事符序列,ASCII水平空格字符(0x20,即空格)是源文件中唯一允许泛起的空缺字符,这意味着:

1、所有其它字符串中的空缺字符都要举行转义。

2、制表符不用于缩进。

2.3.2 特殊转义序列

对于具有特殊转义序列的任何字符(\b, \t, \n, \f, \r, “, ‘及),我们使用它的转义序列,而不是响应的八进制(好比 \012)或Unicode(好比 \u000a)转义。

2.3.3 非ASCII字符

对于剩余的非ASCII字符,是使用现实的Unicode字符(好比∞),照样使用等价的Unicode转义符(好比\u221e),取决于哪个能让代码更易于阅读和明白。

Tip: 在使用Unicode转义符或是一些现实的Unicode字符时,建议做些注释给出注释,这有助于别人阅读和明白。

例如:

String
 unitAbbrev = 
"μs"
;                                 | 赞,纵然没有注释也异常清晰

String
 unitAbbrev = 
"\u03bcs"

// "μs"                    | 允许,但没有理由要这样做

String
 unitAbbrev = 
"\u03bcs"

// Greek letter mu, "s"    | 允许,但这样做显得拙笨还容易失足

String
 unitAbbrev = 
"\u03bcs"
;                            | 很糟,读者基本看不出这是什么

return
 
'\ufeff'
 + content; 
// byte order mark             | Good,对于非打印字符,使用转义,并在必要时写上注释

Tip: 永远不要由于畏惧某些程序可能无法准确处理非ASCII字符而让你的代码可读性变差。当程序无法准确处理非ASCII字符时,它自然无法准确运行, 你就会去fix这些问题的了。(言下之意就是勇敢去用非ASCII字符,若是真的有需要的话)

源文件结构

一个源文件包罗(按顺序地):

1、许可证或版权信息(若有需要)

2、package语句

3、import语句

4、一个顶级类(只有一个)

以上每个部门之间用一个空行离隔。

3.1 许可证或版权信息

若是一个文件包罗许可证或版权信息,那么它应当被放在文件最前面。

3.2 package语句

package语句不换行,列限制(4.4节)并不适用于package语句。(即package语句写在一行里)

3.3 import语句

3.3.1 import不要使用通配符

即,不要泛起类似这样的import语句:importjava.util.*;

3.3.2 不要换行

import语句不换行,列限制(4.4节)并不适用于import语句。(每个import语句自力成行)

3.3.3 顺序和间距

import语句可分为以下几组,根据这个顺序,每组由一个空行分开:

1、所有的静态导入自力成组

2、 com.google imports(仅当这个源文件是在 com.google包下)

3、第三方的包。每个顶级包为一组,字典序。例如:android, com, junit, org, sun

4、 java imports

5、 javax imports

组内不空行,按字典序排列。

民众号 逆锋起笔 专注分享 JavaPython、前端、大厂履历、职业生长干货;天天下昼 14:40 推送,每个程序员值得关注的手艺平台。关注即送小编整理的精品视频教程

3.4 类声明

3.4.1 只有一个顶级类声明

每个顶级类都在一个与它同名的源文件中(固然,还包罗 .java后缀)。

破例:package-info.java,该文件中可没有 package-info类。

3.4.2 类成员顺序

类的成员顺序对易学性有很大的影响,但这也不存在唯一的通用规则。差别的类对成员的排序可能是差别的。最主要的一点,每个类应该以某种逻辑去排序它的成员,维护者应该要能注释这种排序逻辑。

好比, 新的方式不能总是习惯性地添加到类的末端,由于这样就是按时间顺序而非某种逻辑来排序的。

3.4.2.1 重载:永不分离 当一个类有多个组织函数,或是多个同名方式,这些函数/方式应该按顺序泛起在一起,中心不要放进其它函数/方式。

花样

术语说明:块状结构(block-like construct)指的是一个类,方式或组织函数的主体。需要注重的是,数组初始化中的初始值可被选择性地视为块状结构(4.8.3.1节)。

4.1 大括号

4.1.1 使用大括号(纵然是可选的)

大括号与 if,else,for,do,while语句一起使用,纵然只有一条语句(或是空),也应该把大括号写上。

4.1.2 非空块:K & R 气概

对于非空块和块状结构,大括号遵照Kernighan和Ritchie气概 (Egyptian brackets):

1、左大括号前不换行

2、左大括号后换行

3、右大括号前换行

4、若是右大括号是一个语句、函数体或类的终止,则右大括号后换行; 否则不换行。例如,若是右大括号后面是else或逗号,则不换行。

示例:

return
 
new
 
MyClass
() {

  
@Override
 
public
 
void
 method() {

    
if
 (condition()) {

      
try
 {

        something();

      } 
catch
 (
ProblemException
 e) {

        recover();

      }

    }

  }

};

4.8.1节给出了enum类的一些破例。

4.1.3 空块:可以用简练版本

一个空的块状结构里什么也不包罗,大括号可以简练地写成 {},不需要换行。破例:若是它是一个多块语句的一部门(if/else 或 try/catch/finally) ,纵然大括号内没内容,右大括号也要换行。

示例:

void
 doNothing() {}

4.2 块缩进:2个空格

每当最先一个新的块,缩进增添2个空格,当块竣事时,缩进返回先前的缩进级别。缩进级别适用于代码和注释。(见4.1.2节中的代码示例)

4.3 一行一个语句

每个语句后要换行。

4.4 列限制:80或100

一个项目可以选择一行80个字符或100个字符的列限制,除了下述破例,任何一行若是跨越这个字符数限制,必须自动换行。

破例:

1、不能能知足列限制的行(例如,Javadoc中的一个长URL,或是一个长的JSNI方式参考)。

2、 package和 import语句(见3.2节和3.3节)。

3、注释中那些可能被剪切并粘贴到shell中的命令行。

4.5 自动换行

术语说明:一样平常情形下,一行长代码为了制止超出列限制(80或100个字符)而被分为多行,我们称之为自动换行(line-wrapping)。

我们并没有周全,确定性的准则来决议在每一种情形下若何自动换行。许多时刻,对于统一段代码会有好几种有用的自动换行方式。

Tip: 提取方式或局部变量可以在不换行的情形下解决代码过长的问题(是合理缩短命名长度吧)

4.5.1 从那里断开

自动换行的基本准则是:更倾向于在更高的语法级别处断开。

1、若是在 非赋值运算符处断开,那么在该符号前断开(好比+,它将位于下一行)。注重:这一点与Google其它语言的编程气概差别(如C++和JavaScript)。这条规则也适用于以下“类运算符”符号:点分开符(.),类型界线中的&( <TextendsFoo&Bar>),catch块中的管道符号( catch(FooException|BarExceptione)

2、若是在 赋值运算符处断开,通常的做法是在该符号后断开(好比=,它与前面的内容留在统一行)。这条规则也适用于 foreach语句中的分号。

3、方式名或组织函数名与左括号留在统一行。

4、逗号(,)与其前面的内容留在统一行。

4.5.2 自动换行时缩进至少+4个空格

自动换行时,第一行后的每一行至少比第一行多缩进4个空格(注重:制表符不用于缩进。见2.3.1节)。

当存在延续自动换行时,缩进可能会多缩进不只4个空格(语法元素存在多级时)。一样平常而言,两个延续行使用相同的缩进当且仅当它们最先于同级语法元素。

第4.6.3水平对齐一节中指出,不激励使用可变数目的空格来对齐前面行的符号。

4.6 空缺

4.6.1 垂直空缺

以下情形需要使用一个空行:

1、类内延续的成员之间:字段,组织函数,方式,嵌套类,静态初始化块,实例初始化块。

例如:两个延续字段之间的空行是可选的,用于字段的空行主要用来对字段举行逻辑分组。

2、在函数体内,语句的逻辑分组间使用空行。

3、类内的第一个成员前或最后一个成员后的空行是可选的(既不激励也不否决这样做,视小我私家喜欢而定)。

4、要知足本文档中其他节的空行要求(好比3.3节:import语句)

多个延续的空行是允许的,但没有必要这样做(我们也不激励这样做)。

4.6.2 水平空缺

除了语言需求和其它规则,而且除了文字,注释和Javadoc用到单个空格,单个ASCII空格也泛起在以下几个地方:

1、分开任何保留字与紧随其后的左括号( ()(如 if,forcatch等)。

2、分开任何保留字与其前面的右大括号( })(如 else,catch)。

3、在任何左大括号前( {),两个破例:

@SomeAnnotation({a,b})(不使用空格)。String[][]x=foo;(大括号间没有空格,见下面的Note)。

4、在任何二元或三元运算符的两侧。这也适用于以下“类运算符”符号:

类型界线中的&( <TextendsFoo&Bar>)。catch块中的管道符号( catch(FooException|BarExceptione)。foreach语句中的分号。

5、在 ,:;及右括号( ))后

6、若是在一条语句后做注释,则双斜杠(//)双方都要空格。这里可以允许多个空格,但没有必要。

7、类型和变量之间:List list。

8、数组初始化中,大括号内的空格是可选的,即 newint[]{5,6}和 newint[]{5,6}都是可以的。

Note:这个规则并不要求或克制一行的开关或末端需要分外的空格,只对内部空格做要求。

4.6.3 水平对齐:不做要求

Java工具类之:包装类

术语说明:水平对齐指的是通过增添可变数目的空格来使某一行的字符与上一行的响应字符对齐。

这是允许的(而且在不少地方可以看到这样的代码),但Google编程气概对此不做要求。纵然对于已经使用水平对齐的代码,我们也不需要去保持这种气概。

以下示例先展示未对齐的代码,然后是对齐的代码:

private
 
int
 x; 
// this is fine

private
 
Color
 color; 
// this too

private
 
int
   x;      
// permitted, but future edits

private
 
Color
 color;  
// may leave it unaligned

Tip:对齐可增添代码可读性,但它为日后的维护带来问题。思量未来某个时刻,我们需要修改一堆对齐的代码中的一行。这可能导致原本很漂亮的对齐代码变得错位。很可能它会提醒你调整周围代码的空缺来使这一堆代码重新水平对齐(好比程序员想保持这种水平对齐的气概), 这就会让你做许多的无用功,增添了reviewer的事情而且可能导致更多的合并冲突。

4.7 用小括号来限制组:推荐

除非作者和reviewer都以为去掉小括号也不会使代码被误解,或是去掉小括号能让代码更易于阅读,否则我们不应该去掉小括号。我们没有理由假设读者能记着整个Java运算符优先级表。

民众号 逆锋起笔 专注分享 JavaPython、前端、大厂履历、职业生长干货;天天下昼 14:40 推送,每个程序员值得关注的手艺平台。关注即送小编整理的精品视频教程

4.8 详细结构

4.8.1 枚举类

枚举常量间用逗号离隔,换行可选。

没有方式和文档的枚举类可写成数组初始化的花样:

private enum  Suit
 { CLUBS, HEARTS, SPADES, DIAMONDS }

由于枚举类也是一个类,因此所有适用于其它类的花样规则也适用于枚举类。

4.8.2 变量声明

4.8.2.1 每次只声明一个变量 不要使用组合声明,好比 inta,b;。

4.8.2.2 需要时才声明,并尽快举行初始化 不要在一个代码块的开头把局部变量一次性都声明晰(这是c语言的做法),而是在第一次需要使用它时才声明。局部变量在声明时最好就举行初始化,或者声明后尽快举行初始化。

4.8.3 数组

4.8.3.1 数组初始化:可写成块状结构 数组初始化可以写成块状结构,好比,下面的写法都是OK的:

new int[] {0, 1, 2, 3}

new int[] {0,1,2,3}

new int[] {0, 1,2, 3}

new int[]{0, 1, 2, 3}

4.8.3.2 非C气概的数组声明 中括号是类型的一部门:String[]args, 而非 Stringargs[]。

4.8.4 switch语句

术语说明:switch块的大括号内是一个或多个语句组。每个语句组包罗一个或多个switch标签( caseFOO:或 default:),后面随着一条或多条语句。

4.8.4.1 缩进 与其它块状结构一致,switch块中的内容缩进为2个空格。

每个switch标签后新起一行,再缩进2个空格,写下一条或多条语句。

4.8.4.2 Fall-through:注释

在一个switch块内,每个语句组要么通过 break,continue,return或抛出异常来终止,要么通过一条注释来说明程序将继续执行到下一个语句组, 任何能表达这个意思的注释都是OK的(典型的是用 // fall through)。这个特殊的注释并不需要在最后一个语句组(一样平常是 default)中泛起。示例:

switch
 (input) {
case 1:
case 2:
  prepareOneOrTwo();
// fall through
case 3:
   handleOneTwoOrThree();   
break;  
default:
    handleLargeNumber(input);
}

4.8.4.3 default的情形要写出来

每个switch语句都包罗一个 default语句组,纵然它什么代码也不包罗。

4.8.5 注解(Annotations)

注解紧跟在文档块后面,应用于类、方式和组织函数,一个注解独占一行。这些换行不属于自动换行(第4.5节,自动换行),因此缩进级别稳定。例如:

@Override
@Nullable
public String getNameIfPresent() { ... }

破例:单个的注解可以和署名的第一行泛起在统一行。例如:

@Override
 public  int hashCode() { ... }

应用于字段的注解紧随文档块泛起,应用于字段的多个注解允许与字段泛起在统一行。例如:

@Partial
 @Mock
 DataLoader
 loader;

参数和局部变量注解没有特定规则。

4.8.6 注释

4.8.6.1 块注释气概 块注释与其周围的代码在统一缩进级别。它们可以是 /* … /气概,也可以是 // …气概。对于多行的 / … */注释,后续行必须从 *最先, 而且与前一行的 *对齐。以下示例注释都是OK的。

/*

 * This is          // And so           /* Or you can

 * okay.            // is this.          * even do this. */

 */

注释不要封锁在由星号或其它字符绘制的框架里。

Tip:在写多行注释时,若是你希望在必要时能重新换行(即注释像段落气概一样),那么使用 /* … */。

4.8.7 Modifiers

类和成员的modifiers若是存在,则按Java语言规范中推荐的顺序泛起。

public
 
protected
 
private
 
abstract
 
static
 
final
 
transient
 
volatile
 
synchronized
 
native
 
strictfp

命名约定

5.1 对所有标识符都通用的规则

标识符只能使用ASCII字母和数字,因此每个有用的标识符名称都能匹配正则表达式 \w+。

在Google其它编程语言气概中使用的特殊前缀或后缀,如 name_, mName, s_name和 kName,在Java编程气概中都不再使用。

5.2 标识符类型的规则

5.2.1 包名

包名所有小写,延续的单词只是简朴地连接起来,不使用下划线。

5.2.2 类名

类名都以 UpperCamelCase气概编写。

类名通常是名词或名词短语,接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有用的约定来命名注解类型。

测试类的命名以它要测试的类的名称最先,以 Test竣事。例如, HashTest或 HashIntegrationTest。

5.2.3 方式名

方式名都以 lowerCamelCase气概编写。

方式名通常是动词或动词短语。

下划线可能泛起在JUnit测试方式名称中用以分开名称的逻辑组件。一个典型的模式是:test _ ,例如 testPop_emptyStack。并不存在唯一准确的方式来命名测试方式。

5.2.4 常量名

常量名命名模式为 CONSTANT_CASE,所有字母大写,用下划线分开单词。那,到底什么算是一个常量?

每个常量都是一个静态final字段,但不是所有静态final字段都是常量。在决议一个字段是否是一个常量时, 思量它是否真的感受像是一个常量。例如,若是任何一个该实例的观察状态是可变的,则它险些一定不会是一个常量。只是永远不 计划改变工具一样平常是不够的,它要真的一直稳定才气将它示为常量。

Google 出品的 Java 编码规范,强烈推荐,既权威又科学

这些名字通常是名词或名词短语。

5.2.5 异常量字段名

异常量字段名以 lowerCamelCase气概编写。

这些名字通常是名词或名词短语。

5.2.6 参数名

参数名以 lowerCamelCase气概编写。

参数应该制止用单个字符命名。

5.2.7 局部变量名

局部变量名以 lowerCamelCase气概编写,比起其它类型的名称,局部变量名可以有更为宽松的缩写。

虽然缩写更宽松,但照样要制止用单字符举行命名,除了暂且变量和循环变量。

纵然局部变量是final和不能改变的,也不应该把它示为常量,自然也不能用常量的规则去命名它。

5.2.8 类型变量名

类型变量可用以下两种气概之一举行命名:

1、单个的大写字母,后面可以跟一个数字(如:E, T, X, T2)。

2、以类命名方式(5.2.2节),后面加个大写的T(如:RequestT, FooBarT)。

5.3 驼峰式命名法(CamelCase)

驼峰式命名法分大驼峰式命名法( UpperCamelCase)和小驼峰式命名法( lowerCamelCase)。有时,我们有不只一种合理的方式将一个英语词组转换成驼峰形式,如缩略语或不寻常的结构(例如”IPv6”或”iOS”)。Google指定了以下的转换方案。推荐:告辞狗屎代码,请记着这 11 条编码窍门!

名字从 散文形式(prose form)最先:

1、把短语转换为纯ASCII码,而且移除任何单引号。例如:”Müller’s algorithm”将酿成”Muellers algorithm”。

2、把这个效果切分成单词,在空格或其它标点符号(通常是连字符)处分割开。

推荐:若是某个单词已经有了常用的驼峰示意形式,按它的组成将它分割开(如”AdWords”将分割成”ad words”)。需要注重的是”iOS”并不是一个真正的驼峰示意形式,因此该推荐对它并不适用。

3、现在将所有字母都小写(包罗缩写),然后将单词的第一个字母大写:每个单词的第一个字母都大写,来获得大驼峰式命名。除了第一个单词,每个单词的第一个字母都大写,来获得小驼峰式命名。

4、最后将所有的单词连接起来获得一个标识符。

示例:

Google 出品的 Java 编码规范,强烈推荐,既权威又科学

加星号处示意可以,但不推荐。

Note:在英语中,某些带有连字符的单词形式不唯一。例如:”nonempty”和”non-empty”都是准确的,因此方式名 checkNonempty和 checkNonEmpty也都是准确的。

民众号 逆锋起笔 专注分享 JavaPython、前端、大厂履历、职业生长干货;天天下昼 14:40 推送,每个程序员值得关注的手艺平台。关注即送小编整理的精品视频教程

编程实践

6.1 @Override:能用则用

只要是正当的,就把 @Override注解给用上。

6.2 捕捉的异常:不能忽视

除了下面的例子,对捕捉的异常不做响应是少少准确的。(典型的响应方式是打印日志,或者若是它被以为是不能能的,则把它看成一个 AssertionError重新抛出。)

若是它确实是不需要在catch块中做任何响应,需要做注释加以说明(如下面的例子)。

Google 出品的 Java 编码规范,强烈推荐,既权威又科学

破例:在测试中,若是一个捕捉的异常被命名为 expected,则它可以被不加注释地忽略。下面是一种异常常见的情形,用以确保所测试的方式会抛出一个期望中的异常, 因此在这里就没有必要加注释。

Google 出品的 Java 编码规范,强烈推荐,既权威又科学

6.3 静态成员:使用类举行挪用

使用类名挪用静态的类成员,而不是详细某个工具或表达式。

Google 出品的 Java 编码规范,强烈推荐,既权威又科学

6.4 Finalizers: 禁用

少少会去重写 Object.finalize。

Tip:不要使用finalize。若是你非要使用它,请先仔细阅读和明白Effective Java 第7条款:“Avoid Finalizers”,然后不要使用它。

Javadoc

7.1 花样

7.1.1 一样平常形式

Javadoc块的基本花样如下所示:

/**

 * Multiple lines of Javadoc text are written here,

 * wrapped normally...

 */


public
 
int
 method(
String
 p1)
 
{ ... }

或者是以下单行形式:

/** An especially short bit of Javadoc. */

基本花样总是OK的。当整个Javadoc块能容纳于一行时(且没有Javadoc符号@XXX),可以使用单行形式。

7.1.2 段落

空行(即,只包罗最左侧星号的行)会泛起在段落之间和Javadoc符号(@XXX)之前(若是有的话)。除了第一个段落,每个段落第一个单词前都有标签

,而且它和第一个单词间没有空格。

7.1.3 Javadoc符号

尺度的Javadoc符号按以下顺序泛起:@param, @return, @throws, @deprecated, 前面这4种符号若是泛起,形貌都不能为空。当形貌无法在一行中容纳,延续行需要至少再缩进4个空格。

7.2 摘要片断

每个类或成员的Javadoc以一个简短的摘要片断最先。这个片断是异常主要的,在某些情形下,它是唯一泛起的文本,好比在类和方式索引中。

这只是一个小片断,可以是一个名词短语或动词短语,但不是一个完整的句子。它不会以 A{@codeFoo}isa…或 Thismethod returns…开头, 它也不会是一个完整的祈使句,如 Savethe record…。然而,由于开头大写及被加了标点,它看起来就像是个完整的句子。

Tip:一个常见的错误是把简朴的Javadoc写成 /** @return the customer ID /,这是不准确的。它应该写成 /* Returns the customer ID. */。

7.3 那里需要使用Javadoc

至少在每个public类及它的每个public和protected成员处使用Javadoc,以下是一些破例:

7.3.1 破例:不言自明的方式

对于简朴显著的方式如 getFoo,Javadoc是可选的(即,是可以不写的)。这种情形下除了写“Returns the foo”,确实也没有什么值得写了。

单元测试类中的测试方式可能是不言自明的最常见例子了,我们通常可以从这些方式的形貌性命名中知道它是干什么的,因此不需要分外的文档说明。

Tip:若是有一些相关信息是需要读者领会的,那么以上的破例不应作为忽视这些信息的理由。例如,对于方式名 getCanonicalName, 就不应该忽视文档说明,由于读者很可能不知道词语 canonical name指的是什么。

7.3.2 破例:重写

若是一个方式重写了超类中的方式,那么Javadoc并非必须的。

7.3.3 可选的Javadoc

对于包外不能见的类和方式,若有需要,也是要使用Javadoc的。若是一个注释是用来界说一个类,方式,字段的整体目的或行为, 那么这个注释应该写成Javadoc,这样更统一更友好。

在逆锋起笔微信民众号后台回复关键字:规范,可获取高清 PDF 版的下载地址《Google Java编程气概指南/规范》

Google 出品的 Java 编码规范,强烈推荐,既权威又科学

若是你想获取阿里巴巴最新的《Java开发手册》,请关注逆锋起笔微信民众号,在后台回复关键字:java手册,既可获取。

民众号 逆锋起笔 专注分享 JavaPython、前端、大厂履历、职业生长干货;天天下昼 14:40 推送,每个程序员值得关注的手艺平台。关注即送小编整理的精品视频教程

原创文章,作者:28x29新闻网,如若转载,请注明出处:https://www.28x29.com/archives/20862.html