Java 编程风格军规,看这一篇就够了

点击上方"IT牧场",选择"设为星标"技术干货每日送达javascript


来源:谷歌
java



目录

android

  • 源文件基础程序员

  • 源文件结构面试

  • 格式正则表达式

  • 命名约定shell

  • 编程实践编程

  • Javadoc数组


这份文档是Google Java编程风格规范的完整定义。当且仅当一个Java源文件符合此文档中的规则, 咱们才认为它符合Google的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 特殊转义序列

对于具备特殊转义序列的任何字符(, , , , , ", '及),咱们使用它的转义序列,而不是相应的八进制(好比 )或Unicode(好比 )转义。

2.3.3 非ASCII字符

对于剩余的非ASCII字符,是使用实际的Unicode字符(好比∞),仍是使用等价的Unicode转义符(好比∞),取决于哪一个能让代码更易于阅读和理解。

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

例如:

String unitAbbrev = "μs";                                 | 赞,即便没有注释也很是清晰String unitAbbrev = "μs"; // "μs"                    | 容许,但没有理由要这样作String unitAbbrev = "μs"; // Greek letter mu, "s"    | 容许,但这样作显得笨拙还容易出错String unitAbbrev = "μs";                            | 很糟,读者根本看不出这是什么return '' + 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

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

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):

  • 左大括号前不换行

  • 左大括号后换行

  • 右大括号前换行

  • 若是右大括号是一个语句、函数体或类的终止,则右大括号后换行; 不然不换行。例如,若是右大括号后面是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)。这条规则也适用于如下“类运算符”符号:点分隔符(.),类型界限中的&( ),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. 类内的第一个成员前或最后一个成员后的空行是可选的(既不鼓励也不反对这样作,视我的喜爱而定)。

  5. 要知足本文档中其余节的空行要求(好比3.3节:import语句)

多个连续的空行是容许的,但没有必要这样作(咱们也不鼓励这样作)。

4.6.2 水平空白

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

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

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

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

  4. @SomeAnnotation({a,b})(不使用空格)。

  • String[][]x=foo;(大括号间没有空格,见下面的Note)。

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

  2. - 类型界限中的&( )。

  • catch块中的管道符号( catch(FooException|BarExceptione)。

  • foreach语句中的分号。

  1. 在 ,:;及右括号( ))后

  2. 若是在一条语句后作注释,则双斜杠(//)两边都要空格。这里能够容许多个空格,但没有必要。

  3. 类型和变量之间:List list。

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

Note:这个规则并不要求或禁止一行的开关或结尾须要额外的空格,只对内部空格作要求。

4.6.3 水平对齐:不作要求

术语说明水平对齐指的是经过增长可变数量的空格来使某一行的字符与上一行的相应字符对齐。

这是容许的(并且在很多地方能够看到这样的代码),但Google编程风格对此不作要求。即便对于已经使用水平对齐的代码,咱们也不须要去保持这种风格。

如下示例先展现未对齐的代码,而后是对齐的代码:

private int x; // this is fineprivate Color color; // this tooprivate int   x;      // permitted, but future editsprivate Color color;  // may leave it unaligned

Tip:对齐可增长代码可读性,但它为往后的维护带来问题。考虑将来某个时候,咱们须要修改一堆对齐的代码中的一行。这可能致使本来很漂亮的对齐代码变得错位。极可能它会提示你调整周围代码的空白来使这一堆代码从新水平对齐(好比程序员想保持这种水平对齐的风格), 这就会让你作许多的无用功,增长了reviewer的工做而且可能致使更多的合并冲突。

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

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

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@Nullablepublic 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_mNames_name和 kName,在Java编程风格中都再也不使用。

5.2 标识符类型的规则

5.2.1 包名

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

5.2.2 类名

类名都以 UpperCamelCase风格编写。

类名一般是名词或名词短语,接口名称有时多是形容词或形容词短语。如今尚未特定的规则或行之有效的约定来命名注解类型。

测试类的命名以它要测试的类的名称开始,以 Test结束。例如, HashTest或 HashIntegrationTest

5.2.3 方法名

方法名都以 lowerCamelCase风格编写。

方法名一般是动词或动词短语。

下划线可能出如今JUnit测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是:test<MethodUnderTest>_<state>,例如 testPop_emptyStack并不存在惟一正确的方式来命名测试方法。

5.2.4 常量名

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

每一个常量都是一个静态final字段,但不是全部静态final字段都是常量。在决定一个字段是不是一个常量时, 考虑它是否真的感受像是一个常量。例如,若是任何一个该实例的观测状态是可变的,则它几乎确定不会是一个常量。只是永远不 打算改变对象通常是不够的,它要真的一直不变才能将它示为常量。

// Constantsstatic final int NUMBER = 5;static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");static final Joiner COMMA_JOINER = Joiner.on(',');  // because Joiner is immutablestatic final SomeMutableType[] EMPTY_ARRAY = {};enum SomeEnum { ENUM_CONSTANT }// Not constantsstatic String nonFinal = "non-final";final String nonStatic = "non-static";static final Set<String> mutableCollection = new HashSet<String>();static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);static final Logger logger = Logger.getLogger(MyClass.getName());static final String[] nonEmptyArray = {"these", "can", "change"};

这些名字一般是名词或名词短语。

5.2.5 很是量字段名

很是量字段名以 lowerCamelCase风格编写。

这些名字一般是名词或名词短语。

5.2.6 参数名

参数名以 lowerCamelCase风格编写。

参数应该避免用单个字符命名。

5.2.7 局部变量名

局部变量名以 lowerCamelCase风格编写,比起其它类型的名称,局部变量名能够有更为宽松的缩写。

虽然缩写更宽松,但仍是要避免用单字符进行命名,除了临时变量和循环变量。

即便局部变量是final和不可改变的,也不该该把它示为常量,天然也不能用常量的规则去命名它。

5.2.8 类型变量名

类型变量可用如下两种风格之一进行命名:

  • 单个的大写字母,后面能够跟一个数字(如:E, T, X, T2)。

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

5.3 驼峰式命名法(CamelCase)

驼峰式命名法分大驼峰式命名法( UpperCamelCase)和小驼峰式命名法( lowerCamelCase)。有时,咱们有不仅一种合理的方式将一个英语词组转换成驼峰形式,如缩略语或不寻常的结构(例如”IPv6”或”iOS”)。Google指定了如下的转换方案。

名字从 散文形式(prose form)开始:

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

  2. 把这个结果切分红单词,在空格或其它标点符号(一般是连字符)处分割开。

  3. - 推荐:若是某个单词已经有了经常使用的驼峰表示形式,按它的组成将它分割开(如”AdWords”将分割成”ad words”)。须要注意的是”iOS”并非一个真正的驼峰表示形式,所以该推荐对它并不适用。

  4. 如今将全部字母都小写(包括缩写),而后将单词的第一个字母大写:

  5. - 每一个单词的第一个字母都大写,来获得大驼峰式命名。

  • 除了第一个单词,每一个单词的第一个字母都大写,来获得小驼峰式命名。

  1. 最后将全部的单词链接起来获得一个标识符。

示例:

Prose form                Correct               Incorrect------------------------------------------------------------------"XML HTTP request"        XmlHttpRequest        XMLHTTPRequest"new customer ID"         newCustomerId         newCustomerID"inner stopwatch"         innerStopwatch        innerStopWatch"supports IPv6 on iOS?"   supportsIpv6OnIos     supportsIPv6OnIOS"YouTube importer"        YouTubeImporter                          YoutubeImporter*

加星号处表示能够,但不推荐。

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

编程实践

6.1 @Override:能用则用

只要是合法的,就把 @Override注解给用上。

6.2 捕获的异常:不能忽视

除了下面的例子,对捕获的异常不作响应是极少正确的。(典型的响应方式是打印日志,或者若是它被认为是不可能的,则把它看成一个 AssertionError从新抛出。)

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

try {  int i = Integer.parseInt(response);  return handleNumericResponse(i);} catch (NumberFormatException ok) {  // it's not numeric; that's fine, just continue}return handleTextResponse(response);

例外在测试中,若是一个捕获的异常被命名为 expected,则它能够被不加注释地忽略。下面是一种很是常见的情形,用以确保所测试的方法会抛出一个指望中的异常, 所以在这里就没有必要加注释。

try {  emptyStack.pop();  fail();} catch (NoSuchElementException expected) {}

6.3 静态成员:使用类进行调用

使用类名调用静态的类成员,而不是具体某个对象或表达式。

Foo aFoo = ...;Foo.aStaticMethod(); // goodaFoo.aStaticMethod(); // badsomethingThatYieldsAFoo().aStaticMethod(); // very bad

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)以前(若是有的话)。除了第一个段落,每一个段落第一个单词前都有标签 <p>,而且它和第一个单词间没有空格。

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分享。关注我,回复以下代码,便可得到百度盘地址,无套路领取!

•001:《Java并发与高并发解决方案》学习笔记;•002:《深刻JVM内核——原理、诊断与优化》学习笔记;•003:《Java面试宝典》•004:《Docker开源书》•005:《Kubernetes开源书》•006:《DDD速成(领域驱动设计速成)》•007:所有•008:加技术讨论群

往期精彩

PB级数据实时查询,滴滴Elasticsearch多集群架构实践Alibaba Sentinel 规则持久化-拉模式-手把手教程(基于文件)你真的了解 lambda 吗(纠错篇)?如何在 IDEA 使用Debug 图文教程除了负载均衡,Nginx还能够作限流、缓存、黑白名单……漫漫优化路,总会错几步!记一次接口优化!


想知道更多?长按/扫码关注我吧↓↓↓640?wx_fmt=jpeg>>>技术讨论群<<<喜欢就点个"在看"呗^_^