Google官方的Java编程风格规范。与其它的编程风格指南一样,这里所讨论的不仅仅是编码格式美不美观的问题, 同时也讨论一些约定及编码标准。这份规范主要侧重于我们所普遍遵循的规则, 对于那些不是明确强制要求的,我们尽量避免提供意见。
1.1术语说明
术语class可表示一个普通类,枚举类,接口或是annotation类型( @interface
)
术语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,即空格)是源文件中唯一允许出现的空白字符,这意味着:
所有其它字符串中的空白字符都要进行转义。
制表符不用于缩进。
2.3.2 特殊转义序列
对于具有特殊转义序列的任何字符(\b
, \t
, \n
, \f
, \r
, ",
'及),我们使用它的转义序列,而不是相应的八进制(比如 \012
)或Unicode(比如 \u000a
)转义。
2.3.3 非ASCII字符
对于剩余的非ASCII字符,是使用实际的Unicode字符(比如∞
),还是使用等价的Unicode转义符(比如\u221e
),取决于哪个能让代码更易于阅读和理解。
Tip: 在使用Unicode转义符或是一些实际的Unicode字符时,建议做些注释给出解释,这有助于别人阅读和理解。
例如:
Tip: 永远不要由于害怕某些程序可能无法正确处理非ASCII字符而让你的代码可读性变差。当程序无法正确处理非ASCII字符时,它自然无法正确运行, 你就会去fix这些问题的了。(言下之意就是大胆去用非ASCII字符,如果真的有需要的话)
源文件结构
一个源文件包含(按顺序地):
-
许可证或版权信息(如有需要)
-
package语句
-
import语句
-
一个顶级类(只有一个)
以上每个部分之间用一个空行隔开。
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语句可分为以下几组,按照这个顺序,每组由一个空行分隔:
-
所有的静态导入独立成组
-
com.google imports(仅当这个源文件是在 com.google包下)
-
第三方的包。每个顶级包为一组,字典序。例如:android, com, junit, org, sun
-
java imports
-
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风