Google 出品的 Java 编码规范,强烈推荐!

  • 时间:
  • 浏览:66
  • 来源:久爱辅助网_提供小高教程网技术_群哥教程网资讯

来源:google.github.io/styleguide/javaguide.html

这是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 特殊转义序列

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

2.3.3 非ASCII字符

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

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

类式:

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

  1. 左大括号前不换行
  2. 左大括号后换行
  3. 右大括号前换行
  4. 机会右大括号是二个 句子、函数体或类的终止,则右大括号后换行; 有本来不换行。类式,机会右大括号上方是else或逗号,则不换行。

示例:

4.8.1节给出了enum类的一点例外。

4.1.3 空块:都都可以 用简洁版本

二个 空的块状形态里那些本来我涵盖,大括号都都可以 简洁地写成 {},需要换行。例外:机会它是二个 多块句子的一累积(if/else 或 try/catch/finally) ,即使大括号内没内容,右大括号也要换行。

示例:

4.2 块缩进:二个 空格

每当原本刚结束了二个 新的块,缩进增加二个 空格,当块原本结束了时,缩进返回先前的缩进级别。缩进级别适用于代码和注释。(见4.1.2节中的代码示例)

4.3 一行二个 句子

每个句子本来换行。

4.4 列限制:3000或3000

二个 项目都都可以 选泽一行3000个字符或3000个字符的列限制,除了下述例外,任何一行机会超过这个 字符数限制,需要自动换行。

例外:

  1. 不机会满足列限制的行(类式,Javadoc中的二个 长URL,或是二个 长的JSNI法律辦法 参考)。
  2. package和 import句子(见3.2节和3.3节)。
  3. 注释中那些机会被剪切并粘放在shell中的命令行。

4.5 自动换行

术语说明:一般情况报告下,一行长代码为了解决超出列限制(3000或3000个字符)而被分为多行,亲戚亲戚亲们称之为自动换行(line-wrapping)。

亲戚亲戚亲们并没办法 全面,选泽性的准则来决定在每五种情况报告下如可自动换行。本来原本,对于同一段代码会有好几种有效的自动换行法律辦法 。、

Tip: 提取法律辦法 或局部变量都都可以 在不换行的情况报告下解决代码过长的大难题(是合理缩短命名长度吧)

4.5.1 从哪里断开

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

  1. 机会在非赋值运算符处断开,没办法 在该符号前断开(比如+,它将指在下一行)。注意:这个 点与Google其它语言的编程风格不同(如C++和JavaScript)。这条规则也适用于以下“类运算符”符号:点分隔符(.),类型界限中的&( <TextendsFoo&Bar>),catch块中的管道符号( catch(FooException|BarExceptione)
  2. 机会在赋值运算符处断开,通常的做法是在该符号后断开(比如=,它与前面的内容留在同一行)。这条规则也适用于foreach句子中的分号。
  3. 法律辦法 名或构造函数名与左括号留在同一行。
  4. 逗号(,)与其前面的内容留在同一行。

4.5.2 自动换行时缩进相当于 +二个 空格

自动换行时,第一行后的每一行相当于 比第一行多缩进二个 空格(注意:制表符无需于缩进。见2.3.1节)。

当指在连续自动换行时,缩进机会会多缩进不只二个 空格(语法元素指在多级时)。一般而言,二个 连续行使用相同的缩进当且仅当它们原本刚开原本结束了同级语法元素。

第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<string>list。</string>
  8. 数组初始化中,大括号内的空格是可选的,即 newint[]{5,6}和 newint[]{5,6}就有都都可以 的。

Note:这个 规则并暂且求或禁止一行的开关或结尾需要额外的空格,只对内部人员空格做要求。

4.6.3 水平对齐:不做要求

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

这是允许的(有本来在不少地方都都可以 看得人原本的代码),但Google编程风格对此不做要求。即使对于机会使用水平对齐的代码,亲戚亲戚亲们本来我需要去保持这个 风格。

以下示例先展示未对齐的代码,有本来是对齐的代码:

Tip:对齐可增加代码可读性,但它为本来的维护带来大难题。考虑未来某个原本,亲戚亲戚亲们需要修改一堆对齐的代码中的一行。这机会是因为原本很漂亮的对齐代码变得错位。很机会它会提示你调整俯近代码的空白来使这个 堆代码重新水平对齐(比如守护进程员想保持这个 水平对齐的风格), 这就会本来做一点的无用功,增加了reviewer的工作有本来机会是因为更多的合并冲突。

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

除非作者和reviewer都认为再加小括号本来我会使代码被误解,或是再加小括号能让代码更易于阅读,有本来亲戚亲戚亲们不应该再加小括号。亲戚亲戚亲们没办法 理由假设读者能记住整个Java运算符优先级表。

4.8 具体形态

4.8.1 枚举类

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

没办法 法律辦法 和文档的枚举类可写成数组初始化的格式:

机会枚举类也是二个 类,有本来所有适用于其它类的格式规则也适用于枚举类。

4.8.2 变量声明

4.8.2.1 每次只声明二个 变量

暂且使用组合声明,比如 inta,b;。

4.8.2.2 需要时才声明,并尽快进行初始化

暂且在二个 代码块的开头把局部变量一次性都声明了(这是c语言的做法),本来我在第一次需要使用它时才声明。局部变量在声明时最好就进行初始化,机会声明后尽快进行初始化。

4.8.3 数组

4.8.3.1 数组初始化:可写成块状形态

数组初始化都都可以 写成块状形态,比如,下面的写法就有OK的:

4.8.3.2 非C风格的数组声明

中括号是类型的一累积:String[]args, 而非 Stringargs[]。

4.8.4 switch句子

术语说明:switch块的大括号内是二个 或多个句子组。每个句子组涵盖二个 或多个switch标签( caseFOO:或 default:),上方跟着二根绳子 或多条句子。

4.8.4.1 缩进

与其它块状形态一致,switch块中的内容缩进为二个 空格。

每个switch标签后新起一行,再缩进二个 空格,写下二根绳子 或多条句子。

4.8.4.2 Fall-through:注释

在二个 switch块内,每个句子组要么通过 break,continue,return或抛出异常来终止,要么通过二根绳子 注释来说明守护进程将继续执行到下二个 句子组, 任何能表达这个 意思的注释就有OK的(典型的是用 // fall through)。这个 特殊的注释暂且需要在最后二个 句子组(一般是 default)中出現。

示例:

4.8.4.3 default的情况报告要写出来

每个switch句子都涵盖二个 default句子组,即使它那些代码本来我涵盖。

4.8.5 注解(Annotations)

注解紧跟在文档块上方,应用于类、法律辦法 和构造函数,二个 注解独占一行。那些换行不属于自动换行(第4.5节,自动换行),有本来缩进级别不变。类式:

例外:单个的注解都都可以 和签名的第一行出現在同一行。类式:

应用于字段的注解紧随文档块出現,应用于字段的多个注解允许与字段出現在同一行。类式:

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

4.8.6 注释

4.8.6.1 块注释风格

块注释与其俯近的代码在同一缩进级别。它们都都可以 是 /* … */风格,也都都可以 是 // …风格。对于多行的 /* … */注释,后续行需要从 *原本刚结束了, 有本来与前一行的 *对齐。以下示例注释就有OK的。

注释暂且封闭在由星号或其它字符绘制的框架里。

Tip:在写多行注释时,机会你希望在必要时能重新换行(即注释像段落风格一样),没办法 使用 /* … */。

4.8.7 Modifiers

类和成员的modifiers机会指在,则按Java语言规范中推荐的顺序出現。

命名约定

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<MethodUnderTest>_<state>,类式 testPop_emptyStack。暂且指在唯一正确的法律辦法 来命名测试法律辦法 。

5.2.4 常量名

常量名命名模式为 CONSTANT_CASE,删剪字母大写,用下划线分隔单词。

每个常量就有二个 静态final字段,但就有所有静态final字段就有常量。在决定二个 字段不是二个 常量时, 考虑它不是真的感觉像是二个 常量。类式,机会任何二个 该实例的观测情况报告是可变的,则它几乎肯定无需是二个 常量。本来我永远不 打算改变对象一般是过高 的,它要真的时不时 不变能助 将它示为常量。

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

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指定了以下的转换方案。

名字从 散文形式(prose form)原本刚结束了:

  1. 把短语转换为纯ASCII码,有本来移除任何单引号。类式:「Müller’s algorithm」将变成「Muellers algorithm」。
  2. 把这个 结果切分成单词,在空格或其它标点符号(通常是连字符)处分割开。推荐:机会某个单词机会有了常用的驼峰表示形式,按它的组成将它分割开(如「AdWords」将分割成「ad words」)。需要注意的是”iOS”并就有二个 真正的驼峰表示形式,有本来该推荐对它暂且适用。
  3. 现在将所有字母都小写(包括缩写),有本来将单词的第二个 字母大写:每个单词的第二个 字母都大写,来得到大驼峰式命名。除了第二个 单词,每个单词的第二个 字母都大写,来得到小驼峰式命名。
  4. 最后将所有的单词连接起来得到二个 标识符。

示例:

加星号处表示都都可以




,但不推荐。

Note:在英语中,一点涵盖连字符的单词形式不唯一。类式:「nonempty」和「non-empty」就有正确的,有本来法律辦法 名 checkNonempty和 checkNonEmpty也就有正确的。

编程实践

6.1 @Override:能用则用

只本来我合法的,就把 @Override注解给用上。

6.2 捕获的异常:没办法 忽视

除了下面的例子,对捕获的异常不做响应是极少正确的。(典型的响应法律辦法 是打印日志,机会机会它被认为是不机会的,则把它当作二个 AssertionError重新抛出。)

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

例外:在测试中,机会二个 捕获的异常被命名为 expected,则它都都可以 被不加注释地忽略。下面是五种非常常见的情况报告,用以确保所测试的法律辦法 会抛出二个 期望中的异常, 有本来在这里就没办法 必要加注释。

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

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

6.4 Finalizers: 禁用

极少会去重写 Object.finalize。

Tip:暂且使用finalize。机会你没办法 使用它,请先仔细阅读和理解Effective Java 第7条款:“Avoid Finalizers”,有本来暂且使用它。

Javadoc

7.1 格式

7.1.1 一般形式

Javadoc块的基本格式如下所示:

机会是以下单行形式:

基本格式时不时 OK的。当整个Javadoc块能容纳于一行时(且没办法 Javadoc标记@XXX),都都可以 使用单行形式。

7.1.2 段落

空行(即,只涵盖最左侧星号的行)会出現在段落之间和Javadoc标记(@XXX)原本(机会有句子)。除了第二个 段落,每个段落第二个 单词前就有标签 <p>,有本来它和第二个 单词间没办法 空格。

7.1.3 Javadoc标记

标准的Javadoc标记按以下顺序出現:@param, @return, @throws, @deprecated前面这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,原本更统一更友好。

本文由

纯洁的微笑

发布在

ITPUB

,转载此文请保持文章删剪性,并请附上文章来源(ITPUB)及本页链接。

原文链接:http://www.itpub.net/2019/07/17/2435/