这份文档是 Google Java 编程风格规范的完整定义。当且仅当一个 Java 源文件符合此文档中的规则,我们才认为它符合 Google 的 Java 编程风格。
与其它的编程风格指南一样,这里所讨论的不仅仅是编码格式美不美观的问题,同时也讨论一些约定及编码标准。然而,这份文档主要侧重于我们所普遍遵循的规则,对于那些不是明确强制要求的,我们尽量避免提供意见。
在本文档中,除非另有说明:
)
- @interface
其他的术语说明会偶尔在后面的文档出现。
本文档中的示例代码并不作为规范。也就是说,虽然示例代码是遵循 Google 编程风格,但并不意味着这是展现这些代码的唯一方式。示例中的格式选择不应该被强制定为规则。
源文件以其最顶层的类名来命名,大小写敏感,文件扩展名为
。
- .java
源文件编码格式为 UTF-8。
除了行结束符序列,ASCII 水平空格字符 (0x20,即空格) 是源文件中唯一允许出现的空白字符,这意味着:
对于具有特殊转义序列的任何字符 (\b, \t, \n, \f, \r, ",'及 \),我们使用它的转义序列,而不是相应的八进制 (比如
) 或 Unicode(比如
- \012
) 转义。
- \u000a
对于剩余的非 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 字符,如果真的有需要的话)
一个源文件包含 (按顺序地):
以上每个部分之间用一个空行隔开。
如果一个文件包含许可证或版权信息,那么它应当被放在文件最前面。
package 语句不换行,列限制 (4.4 节) 并不适用于 package 语句。(即 package 语句写在一行里)
即,不要出现类似这样的 import 语句:
- import java.util.*;
import 语句不换行,列限制 (4.4 节) 并不适用于 import 语句。(每个 import 语句独立成行)
import 语句可分为以下几组,按照这个顺序,每组由一个空行分隔:
imports(仅当这个源文件是在
- com.google
包下)
- com.google
imports
- java
imports
- javax
组内不空行,按字典序排列。
每个顶级类都在一个与它同名的源文件中 (当然,还包含
后缀)。
- .java
例外:
,该文件中可没有
- package-info.java
类。
- package-info
类的成员顺序对易学性有很大的影响,但这也不存在唯一的通用法则。不同的类对成员的排序可能是不同的。最重要的一点,每个类应该以某种逻辑去排序它的成员,维护者应该要能解释这种排序逻辑。比如,新的方法不能总是习惯性地添加到类的结尾,因为这样就是按时间顺序而非某种逻辑来排序的。
当一个类有多个构造函数,或是多个同名方法,这些函数 / 方法应该按顺序出现在一起,中间不要放进其它函数 / 方法。
术语说明:块状结构 (block-like construct) 指的是一个类,方法或构造函数的主体。需要注意的是,数组初始化中的初始值可被选择性地视为块状结构(4.8.3.1 节)。
大括号与
语句一起使用,即使只有一条语句 (或是空),也应该把大括号写上。
- if, else, for, do, while
对于非空块和块状结构,大括号遵循 Kernighan 和 Ritchie 风格 (Egyptian brackets):
示例:
- return new MyClass() {@Override public void method() {
- if (condition()) {
- try {
- something();
- } catch(ProblemException e) {
- recover();
- }
- }
- }
- };
4.8.1 节给出了 enum 类的一些例外。
一个空的块状结构里什么也不包含,大括号可以简洁地写成
,不需要换行。例外:如果它是一个多块语句的一部分 (if/else 或 try/catch/finally) ,即使大括号内没内容,右大括号也要换行。
- {}
示例:
- void doNothing() {}
每当开始一个新的块,缩进增加 2 个空格,当块结束时,缩进返回先前的缩进级别。缩进级别适用于代码和注释。(见 4.1.2 节中的代码示例)
每个语句后要换行。
一个项目可以选择一行 80 个字符或 100 个字符的列限制,除了下述例外,任何一行如果超过这个字符数限制,必须自动换行。
例外:
和
- package
语句 (见 3.2 节和 3.3 节)。
- import
术语说明:一般情况下,一行长代码为了避免超出列限制 (80 或 100 个字符) 而被分为多行,我们称之为自动换行(line-wrapping)。
我们并没有全面,确定性的准则来决定在每一种情况下如何自动换行。很多时候,对于同一段代码会有好几种有效的自动换行方式。
Tip: 提取方法或局部变量可以在不换行的情况下解决代码过长的问题 (是合理缩短命名长度吧)
自动换行的基本准则是:更倾向于在更高的语法级别处断开。
处断开,那么在该符号前断开 (比如 +,它将位于下一行)。注意:这一点与 Google 其它语言的编程风格不同 (如 C++ 和 JavaScript)。这条规则也适用于以下 "类运算符" 符号:点分隔符 (.),类型界限中的 &(
- 非赋值运算符
),catch 块中的管道符号 (
- <T extends Foo & Bar>
)
- catch (FooException | BarException e
处断开,通常的做法是在该符号后断开 (比如 =,它与前面的内容留在同一行)。这条规则也适用于
- 赋值运算符
语句中的分号。
- foreach
自动换行时,第一行后的每一行至少比第一行多缩进 4 个空格 (注意:制表符不用于缩进。见 2.3.1 节)。
当存在连续自动换行时,缩进可能会多缩进不只 4 个空格 (语法元素存在多级时)。一般而言,两个连续行使用相同的缩进当且仅当它们开始于同级语法元素。
第 4.6.3 水平对齐一节中指出,不鼓励使用可变数目的空格来对齐前面行的符号。
以下情况需要使用一个空行:
多个连续的空行是允许的,但没有必要这样做 (我们也不鼓励这样做)。
除了语言需求和其它规则,并且除了文字,注释和 Javadoc 用到单个空格,单个 ASCII 空格也出现在以下几个地方:
)(如
- (
等)。
- if, for catch
)(如
- }
)。
- else, catch
),两个例外:
- {
(不使用空格)。
- @SomeAnnotation({a, b})
(大括号间没有空格,见下面的 Note)。
- String[][] x = foo;
)。
- <T extends Foo & Bar>
)。
- catch (FooException | BarException e
语句中的分号。
- foreach
及右括号 (
- , : ;
) 后
- )
和
- new int[] {5, 6}
都是可以的。
- new int[] { 5, 6 }
Note:这个规则并不要求或禁止一行的开关或结尾需要额外的空格,只对内部空格做要求。
术语说明:水平对齐指的是通过增加可变数量的空格来使某一行的字符与上一行的相应字符对齐。
这是允许的 (而且在不少地方可以看到这样的代码),但 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 的工作并且可能导致更多的合并冲突。
除非作者和 reviewer 都认为去掉小括号也不会使代码被误解,或是去掉小括号能让代码更易于阅读,否则我们不应该去掉小括号。我们没有理由假设读者能记住整个 Java 运算符优先级表。
枚举常量间用逗号隔开,换行可选。
没有方法和文档的枚举类可写成数组初始化的格式:
- private enum Suit {
- CLUBS,
- HEARTS,
- SPADES,
- DIAMONDS
- }
由于枚举类也是一个类,因此所有适用于其它类的格式规则也适用于枚举类。
不要使用组合声明,比如
。
- int a, b;
不要在一个代码块的开头把局部变量一次性都声明了 (这是 c 语言的做法),而是在第一次需要使用它时才声明。局部变量在声明时最好就进行初始化,或者声明后尽快进行初始化。
数组初始化可以写成块状结构,比如,下面的写法都是 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
- }
中括号是类型的一部分:
, 而非
- String[] args
。
- String args[]
术语说明:switch 块的大括号内是一个或多个语句组。每个语句组包含一个或多个 switch 标签 (
或
- case FOO:
),后面跟着一条或多条语句。
- default:
与其它块状结构一致,switch 块中的内容缩进为 2 个空格。
每个 switch 标签后新起一行,再缩进 2 个空格,写下一条或多条语句。
在一个 switch 块内,每个语句组要么通过
或抛出异常来终止,要么通过一条注释来说明程序将继续执行到下一个语句组,任何能表达这个意思的注释都是 OK 的 (典型的是用
- break, continue, return
)。这个特殊的注释并不需要在最后一个语句组 (一般是
- // fall through
) 中出现。示例:
- default
- switch (input) {
- case 1:
- case 2:
- prepareOneOrTwo();
- // fall through
- case 3:
- handleOneTwoOrThree();
- break;
- default:
- handleLargeNumber(input);
- }
每个 switch 语句都包含一个
语句组,即使它什么代码也不包含。
- default
注解紧跟在文档块后面,应用于类、方法和构造函数,一个注解独占一行。这些换行不属于自动换行 (第 4.5 节,自动换行),因此缩进级别不变。例如:
- @Override@Nullable public String getNameIfPresent() {...
- }
例外:单个的注解可以和签名的第一行出现在同一行。例如:
- @Override public int hashCode() {...
- }
应用于字段的注解紧随文档块出现,应用于字段的多个注解允许与字段出现在同一行。例如:
- @Partial@Mock DataLoader loader;
参数和局部变量注解没有特定规则。
块注释与其周围的代码在同一缩进级别。它们可以是
风格,也可以是
- /* ... */
风格。对于多行的
- // ...
注释,后续行必须从
- /* ... */
开始,并且与前一行的
- *
对齐。以下示例注释都是 OK 的。
- *
- /*
- * This is // And so /* Or you can
- * okay. // is this. * even do this. */
- * //
注释不要封闭在由星号或其它字符绘制的框架里。
Tip:在写多行注释时,如果你希望在必要时能重新换行 (即注释像段落风格一样),那么使用
。
- /* ... */
类和成员的 modifiers 如果存在,则按 Java 语言规范中推荐的顺序出现。
- public protected private abstract static final transient volatile synchronized native strictfp
标识符只能使用 ASCII 字母和数字,因此每个有效的标识符名称都能匹配正则表达式
。
- \w+
在 Google 其它编程语言风格中使用的特殊前缀或后缀,如
,
- name_
,
- mName
和
- s_name
,在 Java 编程风格中都不再使用。
- kName
包名全部小写,连续的单词只是简单地连接起来,不使用下划线。
类名都以
风格编写。
- UpperCamelCase
类名通常是名词或名词短语,接口名称有时可能是形容词或形容词短语。现在还没有特定的规则或行之有效的约定来命名注解类型。
测试类的命名以它要测试的类的名称开始,以
结束。例如,
- Test
或
- HashTest
。
- HashIntegrationTest
方法名都以
风格编写。
- lowerCamelCase
方法名通常是动词或动词短语。
下划线可能出现在 JUnit 测试方法名称中用以分隔名称的逻辑组件。一个典型的模式是:
,例如
- test<MethodUnderTest>_<state>
。并不存在唯一正确的方式来命名测试方法。
- testPop_emptyStack
常量名命名模式为
,全部字母大写,用下划线分隔单词。那,到底什么算是一个常量?
- CONSTANT_CASE
每个常量都是一个静态 final 字段,但不是所有静态 final 字段都是常量。在决定一个字段是否是一个常量时,考虑它是否真的感觉像是一个常量。例如,如果任何一个该实例的观测状态是可变的,则它几乎肯定不会是一个常量。只是永远不
改变对象一般是不够的,它要真的一直不变才能将它示为常量。
- 打算
- // Constants
- static final int NUMBER = 5;
- static final ImmutableList < String > NAMES = ImmutableList.of("Ed", "Ann");
- static final Joiner COMMA_JOINER = Joiner.on(', '); // because Joiner is immutable
- static final SomeMutableType[] EMPTY_ARRAY = {};
- enum SomeEnum {
- ENUM_CONSTANT
- }
-
- // Not constants
- static 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"
- };
这些名字通常是名词或名词短语。
非常量字段名以
风格编写。
- lowerCamelCase
这些名字通常是名词或名词短语。
参数名以
风格编写。
- lowerCamelCase
参数应该避免用单个字符命名。
局部变量名以
风格编写,比起其它类型的名称,局部变量名可以有更为宽松的缩写。
- lowerCamelCase
虽然缩写更宽松,但还是要避免用单字符进行命名,除了临时变量和循环变量。
即使局部变量是 final 和不可改变的,也不应该把它示为常量,自然也不能用常量的规则去命名它。
类型变量可用以下两种风格之一进行命名:
驼峰式命名法分大驼峰式命名法 (
) 和小驼峰式命名法 (
- UpperCamelCase
)。有时,我们有不只一种合理的方式将一个英语词组转换成驼峰形式,如缩略语或不寻常的结构 (例如"IPv6"或"iOS")。Google 指定了以下的转换方案。
- lowerCamelCase
名字从
(prose form) 开始:
- 散文形式
示例:
- 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
只要是合法的,就把
注解给用上。
- @Override
除了下面的例子,对捕获的异常不做响应是极少正确的。(典型的响应方式是打印日志,或者如果它被认为是不可能的,则把它当作一个
重新抛出。)
- 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) {}
使用类名调用静态的类成员,而不是具体某个对象或表达式。
- Foo aFoo = ...;
- Foo.aStaticMethod(); // good
- aFoo.aStaticMethod(); // bad
- somethingThatYieldsAFoo().aStaticMethod(); // very bad
极少会去重写
。
- Object.finalize
Tip:不要使用 finalize。如果你非要使用它,请先仔细阅读和理解 Effective Java 第 7 条款:"Avoid Finalizers",然后不要使用它。
Javadoc 块的基本格式如下所示:
- /**
- * Multiple lines of Javadoc text are written here,
- * wrapped normally...
- */
- public int method(String p1) {...
- }
或者是以下单行形式:
- /** An especially short bit of Javadoc. */
基本格式总是 OK 的。当整个 Javadoc 块能容纳于一行时 ([email protected]),可以使用单行形式。
空行 (即,只包含最左侧星号的行) 会出现在段落之间和 Javadoc 标记 (@XXX) 之前(如果有的话)。除了第一个段落,每个段落第一个单词前都有标签
,并且它和第一个单词间没有空格。
- <p>
标准的 Javadoc 标记按以下顺序出现:
,
- @param
,
- @return
,
- @throws
, 前面这 4 种标记如果出现,描述都不能为空。当描述无法在一行中容纳,连续行需要至少再缩进 4 个空格。
- @deprecated
每个类或成员的 Javadoc 以一个简短的摘要片段开始。这个片段是非常重要的,在某些情况下,它是唯一出现的文本,比如在类和方法索引中。
这只是一个小片段,可以是一个名词短语或动词短语,但不是一个完整的句子。它不会以
或
- A [email protected] Foo} is a...
开头, 它也不会是一个完整的祈使句,如
- This method returns...
。然而,由于开头大写及被加了标点,它看起来就像是个完整的句子。
- Save the record...
Tip:一个常见的错误是把简单的 Javadoc 写成
,这是不正确的。它应该写成
- /** @return the customer ID */
。
- /** Returns the customer ID. */
至少在每个 public 类及它的每个 public 和 protected 成员处使用 Javadoc,以下是一些例外:
对于简单明显的方法如
,Javadoc 是可选的 (即,是可以不写的)。这种情况下除了写 "Returns the foo",确实也没有什么值得写了。
- getFoo
单元测试类中的测试方法可能是不言自明的最常见例子了,我们通常可以从这些方法的描述性命名中知道它是干什么的,因此不需要额外的文档说明。
Tip:如果有一些相关信息是需要读者了解的,那么以上的例外不应作为忽视这些信息的理由。例如,对于方法名
,就不应该忽视文档说明,因为读者很可能不知道词语
- getCanonicalName
指的是什么。
- canonical name
如果一个方法重写了超类中的方法,那么 Javadoc 并非必需的。
对于包外不可见的类和方法,如有需要,也是要使用 Javadoc 的。如果一个注释是用来定义一个类,方法,字段的整体目的或行为,那么这个注释应该写成 Javadoc,这样更统一更友好。
[java 开发篇][代码规范]
来源: http://www.bubuko.com/infodetail-2230556.html