这份文档是Google Java编程风格标准的无缺界说。当且仅当一个Java源文件符合此文档中的规则， 我们才以为它符合Google的Java编程风格。
与其它的编程风格攻略相同，这儿所评论的不只仅是编码格式美不美观的问题， 一同也评论一些约好及编码标准。可是，这份文档首要侧重于我们所遍及遵照的规则， 关于那些@ u D , e不是清楚强制要求的，我们尽量避免供给定见。
1.1 术语说明
在本文档中，除非另有说明：
1、术语class可标明一个一般类，枚举类，接口或是annotar a X r , ttion类型( @interface)2、术语comment_ f U S ^ M #只用来指代完结的注释(implemeA } Kntation comments)，我们不运用“documentation comments”一词，而是用JF ] Y p Tavadoc。
其他的术语阐r 1 _ U J v n明会偶尔在后边的文档出现。
1.2 攻略说明
本文S K U T – P X档中的示例代码并X y _ s C L U ?不作为标准。也就是说，虽然示例代码是遵照Google编程风格，但并不意味着这是展示这些代码的仅有方法。示例中的格式挑选不应该被强制定为规则。
源文件根底
2.1 文件名
源文件以其最顶层的类名来命名，大小写灵敏，文件扩展名为 .java。
2.2 文件编码：UTF-8
源文件编码格式为UTF-8。
2.3 特别字符
2.3.1 空白字符
除了行完毕符序列，ASCII水平空格字符(0x20，即空格)是源文件中仅有容许出现的空白字符，这意味着：
1、全部其它字符串中的空白字符都要进行转义。2、制表符不用于缩进。
2.3.2 特别转义序列
关于具有特别转义序列的任何字符(b,] 9 n A d D / t, n, f, r, “, ‘及)，我们运用它的转义序列，而不是相应的八进制(比方 12)或Unicode(比方 u000a)转义。
2.3.3 非ASCII字符
关于剩余的非ASCII字符，是运用实践的Unicode字符(比方∞)，还是运用等价的Unicode转义符(比方u221e)，取A B 1 & o { B决于哪个能让代码更易于阅读和了解。
Tip:G i L h ? 在运用Unic` s o e 9 O $ {od/ { ( H We转义符j Z 9 % *或是一些实践的Unicode字符时，建议做些注释给出解说，这有助于别人阅读和了解。
例如：
String
unitAbbrev =
"s"
; | 赞，即便没有注释也非常清楚
Striw 3 ] 2 j [ng
unitAbbrev =
"u03bcs"
;
// "s" | 容许，但没有理由要这样做
String
unitAbbreV E : w ; i qv =
"u03bcs"
;
// Greek lp 9 ` q xetter mu, "Z 4 s = e / 6 as" | 容许，但这样做显得蠢笨还简略出错
String
unitAbbrev =t h l 9 Q /
"u03bcs"
; | 很糟，读者根本看不出这是什么
return
'ufeff'
+ content;
// byte order mark | Good，关于非打印字符，运用转义，并在必要时写上注释
Tip: 永久不要因为惧怕某些程序或许无法正确处理非ASCII字符而让你的代码可读性变差。当程序无法正确处理非ASCII字符时，它天然无法正确运转， 你就会去fix这些问题的了。(言下之意就是大胆去用非ASCII字符，假* F * T & 3 z如真的有需求的话)
源文件结构
一个源文r i ] K 3 ? +件包括(按{ H h次第地)：
1、许可证或版权信息(如有需求)2、package句子3、import句子4、一个顶级类(只需一个)
以上~ J 2每/ * Y _个部分之间用一个空行离隔。
3.1 许可证或版权信息
假设一个文件包括许可证或版权信息，那么它应当被放在文件最前面。
3.2 package句子
package句子不换行，列束缚(4.4节)并不适用于package句子。(即pack, T 4 k u Lage句子写在一行里)
3.3 import句子
3.3.1 import不要运用通配符
即，不要出现类似这样的import语C f U 7句：M y u o f b iimportjava.util.*;
3.3.2 不要换行
import句子不换行，列束缚(4.4节)并不适用于import句子。(每个import句子独立成行)
3.3.3 次第和距离
import句子可分为以下几组，按照这个次第，每组由一个空行分隔：
1、全部的静态导入独立成组
2、 com.goog3 ? , H X & m Ele imports(仅当这个源文件是在 com.google包下)
3、第三方的包。每个顶级包为一组，字典序。例如：android, com, junit, org, s* P Q O ] $un
4、 java imports5、 javax imports
组内不空行，按字典序摆放。Q ( . g B R 8 n
3.4 类声明
3.4.1 只需一个顶级类声明
每个顶级类都在一个与它同名的源文件中b c ](当然，还包括 .java后缀)。
破例：package-inf Q *fo.java，该文件中可没H # n J e有 package-info类。
3.4.2 类成员次第
类的成员次第对易学性有很大的影响，但这也不存在仅有的通用规律。( _ m S O 2 P M m不同的类对成员的排序或许是不同的。最重要 T x s的一点，每个类应该以某种逻辑去排序它的成员，保护者应该要能解说这种排序逻辑。
比方， 新的方法不能总是习气性地添加到类的完毕，因为这样就是按时间次第而非某种逻辑来排序的。
3.4.2.1 重载：永不分离
当一个类有多个结构函数，或是多个同名方法，这些函数/方法应该按次第出现在一同，中间不要放进其它6 E Q ) v t函数/方法。
格式
术语说明：块状结构(block-like construct)指的是一个类，方法或结构函数的主体。需求留意的是，8 ; , e m I g A数组初始化中B % r U s的初始值可被3 5 r Z }挑选性地视为块状结构(4.8.3.1节)。
4.1 大括号
4.1.1 运用大括号(即便是可选的)
大括号与 if,els9 P T = 5 .e,for,do,while句子一同运用，即便只需一条句子(或是空)，也应该把大括号写上。
4.1S p _.2h i A ~ 非空块：K & R 风格
关于非空块和块状结构，1 J j 1 9大括号遵照Kernighanu I v 9和Ritchie风格 (Egyptian brackets):
1、左大括号前不换行2、左大括号后换行3、右大括s I { V $号前换行4、假设右大括号是一个h j _ { ^ { ( ( )句子、函数体或类的中止，则右大括号后换行; 不然不换行。例如，假设右大括号后边是else或逗号，则不换行。
示例：
return
ne7 G - T 3 Z Jw
MyClass
() {
@Override
public
void
method() {
if
(condition()) {
try
{
somet- s Qhing();
}
catch
(
ProblemException
e) {
recover();
}w x I
}
}
};
4.8.1节给出了enum类的一些破例。
4.1.3 空h g ?块：可以用简练版别
一个空q – H , !的块状结构里什么也不包括，大括号可以简练地= x Z Z s s写成 {}，不需求换行。破例：假设它是一个多块句子的一部分(if/else 或 try/cai 4 w u = Stch/finally) ，即便大括号内没内容，右大括号也要换行。
示例：
void
doNothing() {}
4.2 块缩进：2个& Z k 0 @空格
每逢初步一个新的块，缩进& O e a W s #添加2个空格，当块完毕时，缩进回来从前的缩进等级。缩进等级适用于代码和注释。(见4.1.2节中的代码示例)
4.3 一行一个T o s @句子
每个句子后要换行。
4.4 列束缚：80或G s t F x = * H100
一个项目能= ~ h够挑选一行80个字符或100个字符的列束缚，除了下述破例，任何一行假设超过这个字符数束缚，有必要自动换行。
破例：
1、不或许满足列束缚的行(例如，Javadoc中的一个长URL，或是一个长的JSNI方法参阅)。
2、 package和 import句子(见3.2节和3.3节)。
3、注释中那些或许被剪切并粘贴到shell中的命令行。
4.5 自动换行
术语说明：一般状况下，一行长~ B + Q o % w 4代码为了避免超出列束缚(80或100个h 9 + G }字符)而被分为多行，我们称之为自动换行(line-wrapping)。
我们并没有全面，确定性的原则来决议在每一种状况下怎么自动换行。许多时分，关于同一段代码会有好几种有效的l S + e K H 4自动换行方法。
Tip: 提取方法或部分变E U ) ; e S 8 ]量可以在不换行的状况下解决代码K m u ^ p Y f过长的问题(是合理 P J [ – g )缩短命名长度吧)
4.5.1 从哪里断开
自动换行的根本原则是：更倾向于在更高的语法等级处断开。
1、假设在 非赋值运算符处断开，那么在该符号前断开(比方+，它将位于下一行)。留意：这一点与Google其它言语的编程风格不同(如C++和JavaS{ U 6 d ] V – ; `cript)。这^ J S : . 3条规则也适用于以下“类运算符”符号：点分隔符(.)，类型鸿沟中的&（ <TextendsFoo&Bar>)，catch块中的管道符号( catch(FooException|BarExceptione)
2、假设在 赋值运算符处断开，一般的做法是在该符号后断开(比方=，它与k r P : | t X前面R | { a 8 v r ~的内容留在同一行)9 . N ~ Q w 5 L /。这条规b o ; , = u f :矩也适用于 foreach句子中的分号。
3、方法名或结构函数名与左括号留在同一行。
4、逗号(,)与其前面的内F T H I Z 7容留在同一行。
4.5.2 自动换行时缩进至少+4个空格
自动换行时，第一行后的每一行至少比第一行多缩进4个空格(留意：制表符不用于缩进。见2.3.1节)。
当存在连续主_ + E J Y 7动换行时，缩进或许会多缩进不只4个空格(语法元素存q P v . 4 H 8在多级时)。一般来说，两个连续行运用相同的缩进当且仅当它们初步于同级语法元素。
第4.6.3水平对齐一节中指出，不鼓动运用可变数目的空格来对齐前面行的符号。
4.6 空白
4.6.1 垂直空白
以下状况需求运用一个空行：
1、类内连续的成员之间：字段，结构函数，方法，嵌套类，静态初始化块– U l + j w，实例初始化块。
例如：两个连续字段之c U P # D C 2 l Z间的空行是可选的，用于字段的空行首要用来对字段进行逻辑分组。
2、在函数体内，句子的逻辑分组间运用空行。
3、类内的第一个成员前或终究一个成员后的空行是可选的(既不鼓动也不敌对这样做，视个人喜爱而定)。
4、要满足本文档中其他节的空行要求(比方3.3节：importq w ? C B _ q句子)
多个连续的空行是容许的，但没有必要这样做(我们也不鼓动这样做)。
4x 0 2 9.6.2 水平空白
除了言语需求和其它规则，并且除了文字# / L，注释和Javadoc用到单个空格，单个ASCII空格也O x V @ x q出现在以下几个当地s O V d B ` u ~ l：
1、分隔任何保留字与紧随其后的左括号( ()(如 if,forcatch等)。
2R ! ~ ! P W、分隔任何保留字与其前面的右大括号( })(如 else,catch)。
3、在任何左大括号前( {)，两个破例：
@SomeAnnotation({a,b})(不运用空格)。String[][]x=foo;(大括号间没有空格，S j g见下面的Note)。
4、在任何二元或三元运算符的两头。这也适用于以下“类运算符”符号：
类型鸿沟中的&( <TextendsFoo&Bar>)。catch块中的管道符号( cat* p w 3ch(FooException|BarExceptione)。foreach句子中的分号。
5、在 ,:;及右括号( ))后
6、假设在一条句子后做注释，则双斜杠(//)两头都要空格。这儿可以容许多个空格O & X 0 T A，但没有必要。
7、类型和变量之间：Listlist。
8、数组初始化中，大括号内的空格是可选的，即 newint[]{5,6}和 newint[]{5,6}都3 U q 是可以的。
Not L 0 pe：这个规则并不要求或阻止一行的开关或完毕需求额外的空格，只对内部空r V d S = * 3格做要求。
4.6.3 水平对齐：不做要求
术语说明：水平对齐指的是通过添加可变数量的空格来使某一行的字符与上一行的相应字符对齐。
这是– v / U容许的(并且在不少当地可以看到这样的代码)& 8 X G T，但Google编程风格对此不做要求。即便关于现已运用水平对齐的代码，我们也不U – o ? & 7需求去坚持这种风格* U n p x Z 7 ) 8。
以下示例先展示未对齐的代码，然后是对齐的代码：
private
int
x;
// this is fine
privat- ^ J z h M K le
Color
color;
// this too
private
int
x;
// permitted, but future edits
private
Co1 - #lor
color;
// may leave it unaligned
Tip：对齐可添加代码可读性，但它为日后的保护带来问题。考虑未X U ] q & M b O来某个时分，我们需求h [ u i U ^ F D i修正一堆对齐的代码中的一行。这或许导– ^ K _ k致本来很漂亮的对齐代码变得错位。很或许它会提示你调整周围代码的空白来使这一堆代码从头水平对齐(比方程0 _ n x a序员想坚持这种水平对齐的风格)， 这就会让你做许多的无用功，添加了reviewer的作业并且或许导致更多的吞并抵触。
4.7 用小括号来约束组：举荐
除非作4 ; % H n ] k W者和reviewe? y C l Gr都以为去掉小括号也不会使代码被误解，或是去掉小括号能让代码更易于Y 2 S 0 T Z )阅读，不然我们不应该去掉小括号。我们没有理由假设读者能记住整个Java运算符优先级表。
4.8 具体结构
4.8.1 枚举J d h m z V类
枚举常 p H = $ } k s U量间用逗号离| 0 2 S ;隔，换行可选。
没有方法和文档的枚举类可写成数组初始化的格式：
private
enum
Suit
{ CLUBS, HEARTS, SPADES, DIAMONDX g t W / Y v HS }
因为枚举类也是一个类，因此全部适用于其它类的格式规则也适用于枚举类。
4.8.2 变量声明
4.8.2.1 每次只声明一个变量
不要运用组合声明/ W ; @ k =，比方 inta,b;
4.8.2.2 需求时才声明，并从速进行初始化
不要在一个代码块的开始把部分变量一次性都声明晰(这是c言语的做法)，而是在第一次需求运用它时才声明。部分变量在声明时最好就进行初始化，或许声明后赶p % 5 u p 2 b d %快进行初始化。
4.Z ~ h H F b8.3 数组
4.8.3.1 数组初始化：可写成块状结构
数组初始化可以写成块状结构，比方，下面的写法都是OK的：
new int [] {
0，1，2，3
}
new int[ ] {{ g 4 B 6 k K (
0，
1，
2，
3，
}
new int[ ] {
0, 1,
2, 3
}
new int[ ]{ 0，1，2，3}
4.8.3.2 非C风格的数组声明
中括号是类型的一部分：String[]args， 而非 Stringargs= – O 9[]。
4.8.4 switch句子
术语说明：switch块的大括号内是一个或多个句子% R O组。每个句子组包括一个或多个switch标签( caseFOO:h B R v或 default:)，后边跟着一条或多条句子。switch case 支撑的 6 种数据类型，举荐我们看下。
4.8.4.1 缩进
与其它块状( N 5 / % . `结构一同，switch块中的内容缩进为2个空格。
每个switch标签后新起一行，再缩进2个空格，写下一条或多条句子。
4.8.4.2 Fall-through：注释
在一个switch块内，每个句子组要么通过 break,cI $ J p ^ #ontinue,r] | @eturn或抛出反g | V ? w常来中止，要么通过一条注释来说明程序将继续履? W e H #行到下一个句子组K : ! . p a， 任何能表达这个意思的注释都是OK的(典型的是用 // fall through)。这个特别的注释并不需求在终究一个句子组(一般是 default)中出现。示例：
switch (input) {
case 1:
case 2:
prepareOneOX d I ? YrTwo();
// fall throJ i O h d 1ugh
case 3:
handleOneTwoOrThree();
bv ` M + p U V W Zreak;
default:
handleLarge* 5Number(input);
}
4.k ^ q M T W M 88.4.3 default的状况要写出来
每个switch句子都包括一个 default句子组，即便它什么代码也不包括。
4.8.5 注解(Annotations)
注解紧跟在文档块后边，应用于类、s G ( Z C Y Z y =方法和结构函数，一个注解独占一行。这些换行不属于自动换行(第4.5节，自动换行)，因此缩进等级不变。例如 ` . B $：
@Override
@Y y i ( 5Nullable
publice l ; U String getNameIfPresent() { ... }
破例：单个的注解可以和签名的第一行出现在同一行。例如：
@Override publi* 1 a Q n mc int hashCode(l d ) Y m m L) { ... }
应用于字段的注解紧随文档块出现，应用于字段的多$ T Q 9 R y个注解容许与字段出现在同一行。例如：
@Partia] ^ C u E =l @Mock DataLoader loader;
参数和部分变量注解没有特定规则。
4.8.6 注释
4.8.6.1 块注释风格
块注释与其周围的代码在同一缩进等级。它们可以是 /* …
… */注释，后续U ` x `行有必要从 *初步， 并且与前一行0 r L b的 *对I , : _ $齐。以下示例注释. B M O z t s都是OK的。
/*
* This is // And so /* Or you can
* okay. // is this. * even do thisS L y _ X / g % y. */
*/
注释不要关闭在由星号或其它字符制造的结– – j k S H % –构里。
Tip：在写多行注释时，假设你期望在必要时能从头换行(即注释像阶段风格相同Q N D y C 9 x | T)，那么运用 /* … */。
4.8.7 Modifiers
类和成员的modifiers假设存在，则按Java言语标准中举荐的次第呈, 2 g : A s d现。
public protected po P { + R # p Vrivate ab+ o ) H 6 l Qstract static final transient volatile synchronized native strictfp
命名约好
5.1 对全部标识符都通用的规则
标识符只能运用ASCII字母和数字，因此每个有效的标识符称谓都T i O L q = a能匹配正则表达式 w+。
在Google其它编程言语风格中运用的特别前缀或后缀，如 name_, mName, s_name和 kName，在Java编程风格中都不再运用。举荐阅读：优异 Java 程序员写代码的风格。
5.2 标识符类型的规则
5.2.1 包名
包名全部小写，连续的单词只是. 0 u .简略地连接起来，不运用下划线。
5.2.2 类名
类名都以 UpperCamelCase风格编写。
类名一般是名词或b m p ~ +名词短语，接口称谓有时或许是形容词或形容词短语。现在还没有特定的规则或行之有效的约好来命名注解类型。
检验类的命名以它要检验R a s 0 2 L的类的称谓初步，以 Test完毕。例如，8 _ M 3 V u m c HashTest或 HashIntegrationTest。
5.2.3 方法% ) p h 3 z s e名
方法名都以 lowerCamelCase风格编写。
方法名一般是动词或动词短语。
下划线或许出现在JUnit检验方法称谓中用以分隔称谓的逻辑组件。一个典型的模式是：test_，例如 testPop_emptyStack。并不存在仅有正确的方法来命名检验方法。
5.2.4 常量名
常量名命名模式为 CONSTANT_CASE，全部字母大写，用下划线分隔单词。那，到底什么算是一个常量？
每个常量都是一个静态final字段，但不是全部静态final字段都是常* / – i A量。在决议一个字段是否是一个常量时， 考虑它是否真的感觉像是一个常量。例如，假设任何一个该实例的观测状况是可变的，则它简直必定不会是一个常量。只是永久不 计划改动方针一般是不可的，它要真f f G $ U P的一向不变才干将它示为常量。
// Constants
static final int NU* 1 ` I P MMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Edq k 3 X Z H =","Ann");
static fina2 b P x ? Q Jl Joiner COMMA_JOINER = Joiner.on(',');n N e Q a i //z 1 M O @ 5 } because Joiner is immutK ) x 7 U 3 o 0able
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeE# i w / } znumA z , * 9 F { ENUM_COr / rNSTANT }
// Not constan7 j ^ # Pts
static String n* p VonFinal = "non-final";
final String nonStatic = "non-static";
static fG n . v % 3inal Set<a j ( t RString> mutableCollection = new HashSetP . J & ` 8<String>();
staticp p G h : & D K o finap s , y L ! B W }l Immut; ] r , Q v s ableSet<SomeMutableType> mutab9 g { 2 l ) u O cleElements = ImmutableSet.of(mutable);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final Stv ! y $ring[] nonEmptyArrayU X # S 0 ) ; = {"these", "can", "chM 1 n r i /ange"};
这些名字一般是名词或名词短语。
5.2A ^ 7 @ : A 9.5 非常量字段名
非常量字段名以 lowerCamelCase风格0 ! E } J编写。
这些名字一般是名词或名词短语。
5.2.6 参数名
参数名以 lowerCamelCase风格编写。
参数应该避免用单个字符命名。
5.2.7 部分变量名
部分变量名i a ` 9 h A v I以 lowerCaS d 4 7 E G [ m 6melCase风格编写，比起其它类型的称谓，部分变量名可以有更为宽松的缩写。
虽然缩写更宽松，但还是要避免用单字符进行命名，除了暂时变量和循环变量。
即便部分变量是final和不可改动的，也不应该把它示为常量，天然也不能用常量的规则去命名它。
5.2.8 类型变量名
类型变8 , [ h j Z量可用以下两种风格之一进行命名：0 O 7 T N N –
1、单个的大写字母，后边可以跟一个数字(如：E, T, X, T2)。2、以类命名方法(5.2.2节)，后5 f ]边加个大写的T(如：R2 A q & Y Y p JequestT, FooBa{ ^ m Q * ) (rT)。
5.3 驼峰式命名法(CamelCase)
驼峰式命名法分大驼峰式命名法q 1 4( UpperCamelCase)和小驼峰式命名法( lowerCamelCase)。有时m E * & $ 5，我们有不只一种合理的方法将一个英语词组转化成驼峰方法，如缩略语或不寻常的结构(例如”IPv6”或”iOS”)。Google指定了以下的转0 = ^ { m ^ u w ^化计划。举荐：离别狗屎代码，请记住这 11 条编码秘诀！
名字从 散文方法(prose form)初步:o u z !
1、把短语转化为纯ASCII码，并且移除任何单引号。例如E t Y ` # m L `：”Mller’s algoriy ] R N q i k .thm= ] H 6 t } j”将变成”Muellers algorithm”。
2、把这个结果切分红单词，在空格或其它标点符号(一般是连字符)处置割开。
举荐：假设某个单词现已有了常用的驼峰标明方法，按它的组成将它分割开(如”AdWords”将分割成G x o”ad words”)。需求留意的是”iOS”并不是一个真正的驼峰标明方法，因此该举荐对它并不适用。
3、现在将全部字母都小写(包括缩写)，然后将单词的第一个字母大写：每个单词的第一个字母都大写，来得到大驼峰式T G + 6 d 1 G命名。除了第一个单词，每个单词的第一个字母都大写，来得到小驼峰式命名。
4、终究将全部的单词连接起来得到一个标识符。
示例：
加星号处标明可以，但不举荐。
Note：在英语中，某些带有连字符K M % p B的单词方法不只有# v ] ( L y $ :。例如：”nonempty”和”no? D + o # [ : 4n-em5 M w u a Y Qpty”都是正确? 7 v h 1的，因此方法名3 ~ ] k checkNonempty和 checkNonEmpty也都是正确的。
编程实践
6.1 @Override：能用则用
只需是合法的，就把 @q p I *Override注解给用上。m A + & S
6.2 捕获的失常：不能忽视
除了下面的比方，对捕获的失常不做照应是很少正确的。(典型的照应方法是打印日志，或许假设它被以为是不或许的，则把它当作一个 AssertionError从头抛出。)
假设它确实是不需求在Q l N n W O c _ ,catch块中做任何照应，需求( : m X 7 &做注释加以说明(如下面的比方)。
破例：在测? | 6 V S验中，假. L Z d %如一个捕获的失常被命名为 expected，则它可以被不加注释地忽略。下面是一种非常常见W [ 2 n 3 Y A的情形，用以确保所检验的方法会抛出一个期望中的失常， 因此在这儿就没有必要加注释。
6.3 静态成员：运用类进行调用
运/ D O e e 6用类名调用静态的类成员，而不是具体某个方针或表达式。
6.4 Finalizv w 6 } @ W O ;ers: 禁用
很少会去重写 Object.finalize。
Tip：不要运用finaw } T gl/ c S y ! p ]ize。假设你非要运用它，请先仔细阅读和了解Effective Java 第7条款：“Avoid Finalizers”，然后不要运用它。
Javadoc
7.1 格式
7.1.1( w = ~ S 0 m T T 一般方法
Javadoc块的根本格式如下所示：
或许是以下单行方法：
/** An especially short bit of Javadoc. */
根本格式总是OK的。当整个Javv # 1 s k X B /adoc块能容} z – @ Q j U y纳于一行时(且没有Javadocn 7 | , [ 5 j v符号@XXX)，可以运用单行方法。
7.1.2 阶段
空行(即，只包括最左边4 : M / 3 – Z星号的行)会出现在阶段之间和Javadoc符号(@XXX)之前(假设有的话)。除了第一个阶段，每个阶段第一个单词前都有标签
，并且它和第一个单词间没有空格。
7.1.3 Javadoc符号
标准的Javadoc符号按以下次第出现：@param, @return, @_ i g : n z /th| E P T @ W w /rows, @deprecated, 前V S R = 4 m面这4种符号假设出现，描绘都不能为空。当描绘无法在一行中包容，连续行需求至少再缩进4个空格。
7.2 摘要X 2 } B ` o S片段
每个类或成C x , r b s员的Jav7 ^ 6 t Hadoc以一个简短的摘要片段初步。这个片段是非常重要的，在某些状况下，它是仅有出现的文本， G 2 C X 9 y K比方在类和方法索引中。
这只是一个小} R ` e K S片段，可以是一个名词短语或动词短语，但不是一个完Z 7 n w a @ _ |好的句子。它D K ` I l 1 $不会以 A{@codeFoo}isaO T b l q W…或 Thismethod returns…开始= j ? 0 R 6, 它也不会是一个无缺的祈使句，如 Savethe record…。可是，因为开始大写及被加了标点，它看起来就像是个无缺的句子。
Tip：一个常见的过错是把简略的Javadoc写成 /** @return the customer ID
* Returns the customer ID. */。
7.3 哪里需求运F { ` . N用Javadoc
至少在每个public类及它的每个public和9 q t Z ?protected成员处运用Javadoc，以下是一些破例：
7.3.1 破例：不言自明的方法
关于简略明显的方法/ 8 `如 getFoo，Javadoc是可选的(即，是可以不写的)。这种状况下除了写“Returns the foo”，确实也没有什么值得写了。
单元检验类中的检验方法或许是不言自明的最常见比方了，我们一般可以从这些方法的描绘性命名中知道它是干什么的，因此不需求额外的( f X G _ 1 $文档说明。
Tip：假设有一些相关信息是需求读者了解的，那么以上的破例不应作: 0 ` b为忽视这些信息的理由。例如，关于方法名 get ^ 3 XCanonicalName， 就不应该忽视文档说明，因为读者很或. f G 2 / A n 8 7许不知道词语 canonical name指的是什么。
7.3.2 破例：重写
假设一个方法重写了超1 J ~ |类中? 6 ; _的方法，那么Javadoc并非必需的。
7.3.3 可选的Javadoc
关于包外不可见的类和方法，如有需求，也是要运用Javadoc的。假设一个注释是用来界说一个类，方法，字段的整体目的或行为， 那么这个注释应该写~ 2 ^ _成Javadoc，这样更共同更友爱。
原文：google.github.io/styleguide/javaguide.ht# n nml
译者: – ` O h K L u：Hawstein
来历：hawsg w S } & c Atein.com/2014/01/20/google-java-styl4 T e l 6 ue/
欢迎注重我的微信大众号「码农包围」，分享Python、i R y _ }Java、大数据、机器学习、人工智能等技术，注重{ J s码农技术提升•职场包围•思维跃迁，20万+码农成长充电第一站，陪有希望的你一同成长
