這份文檔是Google Java編程風格規(guī)范的完整定義。當且僅當一個Java源文件符合此文檔中的規(guī)則， 我們才認為它符合Google的Java編程風格。

與其它的編程風格指南一樣，這里所討論的不僅僅是編碼格式美不美觀的問題， 同時也討論一些約定及編碼標準。然而，這份文檔主要側(cè)重于我們所普遍遵循的規(guī)則， 對于那些不是明確強制要求的，我們盡量避免提供意見。

1.1 術(shù)語說明

在本文檔中，除非另有說明：

1. 術(shù)語class可表示一個普通類，枚舉類，接口或是annotation類型(?@interface)
2. 術(shù)語comment只用來指代實現(xiàn)的注釋(implementation comments)，我們不使用“documentation comments”一詞，而是用Javadoc。

其他的術(shù)語說明會偶爾在后面的文檔出現(xiàn)。

1.2 指南說明

本文檔中的示例代碼并不作為規(guī)范。也就是說，雖然示例代碼是遵循Google編程風格，但并不意味著這是展現(xiàn)這些代碼的唯一方式。示例中的格式選擇不應該被強制定為規(guī)則。

源文件基礎(chǔ)

2.1 文件名

源文件以其最頂層的類名來命名，大小寫敏感，文件擴展名為?.java。

2.2 文件編碼：UTF-8

源文件編碼格式為UTF-8。

2.3 特殊字符

2.3.1 空白字符

除了行結(jié)束符序列，ASCII水平空格字符(0x20，即空格)是源文件中唯一允許出現(xiàn)的空白字符，這意味著：

1. 所有其它字符串中的空白字符都要進行轉(zhuǎn)義。
2. 制表符不用于縮進。

2.3.2 特殊轉(zhuǎn)義序列

對于具有特殊轉(zhuǎn)義序列的任何字符(\b, \t, \n, \f, \r, ", '及)，我們使用它的轉(zhuǎn)義序列，而不是相應的八進制(比如?\012)或Unicode(比如?\u000a)轉(zhuǎn)義。

2.3.3 非ASCII字符

對于剩余的非ASCII字符，是使用實際的Unicode字符(比如∞)，還是使用等價的Unicode轉(zhuǎn)義符(比如\u221e)，取決于哪個能讓代碼更易于閱讀和理解。

Tip: 在使用Unicode轉(zhuǎn)義符或是一些實際的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，對于非打印字符，使用轉(zhuǎn)義，并在必要時寫上注釋

Tip: 永遠不要由于害怕某些程序可能無法正確處理非ASCII字符而讓你的代碼可讀性變差。當程序無法正確處理非ASCII字符時，它自然無法正確運行， 你就會去fix這些問題的了。(言下之意就是大膽去用非ASCII字符，如果真的有需要的話)

源文件結(jié)構(gòu)

一個源文件包含(按順序地)：

1. 許可證或版權(quán)信息(如有需要)
2. package語句
3. import語句
4. 一個頂級類(只有一個)

以上每個部分之間用一個空行隔開。

3.1 許可證或版權(quán)信息

如果一個文件包含許可證或版權(quán)信息，那么它應當被放在文件最前面。

3.2 package語句

package語句不換行，列限制(4.4節(jié))并不適用于package語句。(即package語句寫在一行里)

3.3 import語句

3.3.1 import不要使用通配符

即，不要出現(xiàn)類似這樣的import語句：importjava.util.*;

3.3.2 不要換行

import語句不換行，列限制(4.4節(jié))并不適用于import語句。(每個import語句獨立成行)

3.3.3 順序和間距

import語句可分為以下幾組，按照這個順序，每組由一個空行分隔：

1. 所有的靜態(tài)導入獨立成組
2. com.google?imports(僅當這個源文件是在?com.google包下)
3. 第三方的包。每個頂級包為一組，字典序。例如：android, com, junit, org, sun
4. java?imports
5. javax?imports

組內(nèi)不空行，按字典序排列。

3.4 類聲明

3.4.1 只有一個頂級類聲明

每個頂級類都在一個與它同名的源文件中(當然，還包含?.java后綴)。

例外：package-info.java，該文件中可沒有?package-info類。

3.4.2 類成員順序

類的成員順序?qū)σ讓W性有很大的影響，但這也不存在唯一的通用法則。不同的類對成員的排序可能是不同的。最重要的一點，每個類應該以某種邏輯去排序它的成員，維護者應該要能解釋這種排序邏輯。比如， 新的方法不能總是習慣性地添加到類的結(jié)尾，因為這樣就是按時間順序而非某種邏輯來排序的。

3.4.2.1 重載：永不分離

當一個類有多個構(gòu)造函數(shù)，或是多個同名方法，這些函數(shù)/方法應該按順序出現(xiàn)在一起，中間不要放進其它函數(shù)/方法。

格式

術(shù)語說明：塊狀結(jié)構(gòu)(block-like construct)指的是一個類，方法或構(gòu)造函數(shù)的主體。需要注意的是，數(shù)組初始化中的初始值可被選擇性地視為塊狀結(jié)構(gòu)(4.8.3.1節(jié))。

4.1 大括號

4.1.1 使用大括號(即使是可選的)

大括號與?if,else,for,do,while語句一起使用，即使只有一條語句(或是空)，也應該把大括號寫上。

4.1.2 非空塊：K & R 風格

對于非空塊和塊狀結(jié)構(gòu)，大括號遵循Kernighan和Ritchie風格 (Egyptian brackets):

• 左大括號前不換行
• 左大括號后換行
• 右大括號前換行
• 如果右大括號是一個語句、函數(shù)體或類的終止，則右大括號后換行; 否則不換行。例如，如果右大括號后面是else或逗號，則不換行。

示例：

return?new?MyClass()?{??@Override?public?void?method()?{????if?(condition())?{??????try?{????????something();??????}?catch?(ProblemException?e)?{????????recover();??????}????}??}};

4.8.1節(jié)給出了enum類的一些例外。

4.1.3 空塊：可以用簡潔版本

一個空的塊狀結(jié)構(gòu)里什么也不包含，大括號可以簡潔地寫成?{}，不需要換行。例外：如果它是一個多塊語句的一部分(if/else 或 try/catch/finally) ，即使大括號內(nèi)沒內(nèi)容，右大括號也要換行。

示例：

void?doNothing()?{}

4.2 塊縮進：2個空格

每當開始一個新的塊，縮進增加2個空格，當塊結(jié)束時，縮進返回先前的縮進級別。縮進級別適用于代碼和注釋。(見4.1.2節(jié)中的代碼示例)

4.3 一行一個語句

每個語句后要換行。

4.4 列限制：80或100

一個項目可以選擇一行80個字符或100個字符的列限制，除了下述例外，任何一行如果超過這個字符數(shù)限制，必須自動換行。

例外：

1. 不可能滿足列限制的行(例如，Javadoc中的一個長URL，或是一個長的JSNI方法參考)。
2. package和?import語句(見3.2節(jié)和3.3節(jié))。
3. 注釋中那些可能被剪切并粘貼到shell中的命令行。

4.5 自動換行

術(shù)語說明：一般情況下，一行長代碼為了避免超出列限制(80或100個字符)而被分為多行，我們稱之為自動換行(line-wrapping)。

我們并沒有全面，確定性的準則來決定在每一種情況下如何自動換行。很多時候，對于同一段代碼會有好幾種有效的自動換行方式。

Tip: 提取方法或局部變量可以在不換行的情況下解決代碼過長的問題(是合理縮短命名長度吧)

4.5.1 從哪里斷開

自動換行的基本準則是：更傾向于在更高的語法級別處斷開。

1. 如果在?非賦值運算符處斷開，那么在該符號前斷開(比如+，它將位于下一行)。注意：這一點與Google其它語言的編程風格不同(如C++和JavaScript)。這條規(guī)則也適用于以下“類運算符”符號：點分隔符(.)，類型界限中的&（?)，catch塊中的管道符號(?catch(FooException|BarExceptione)
2. 如果在?賦值運算符處斷開，通常的做法是在該符號后斷開(比如=，它與前面的內(nèi)容留在同一行)。這條規(guī)則也適用于?foreach語句中的分號。
3. 方法名或構(gòu)造函數(shù)名與左括號留在同一行。
4. 逗號(,)與其前面的內(nèi)容留在同一行。

4.5.2 自動換行時縮進至少+4個空格

自動換行時，第一行后的每一行至少比第一行多縮進4個空格(注意：制表符不用于縮進。見2.3.1節(jié))。

當存在連續(xù)自動換行時，縮進可能會多縮進不只4個空格(語法元素存在多級時)。一般而言，兩個連續(xù)行使用相同的縮進當且僅當它們開始于同級語法元素。

第4.6.3水平對齊一節(jié)中指出，不鼓勵使用可變數(shù)目的空格來對齊前面行的符號。

4.6 空白

4.6.1 垂直空白

以下情況需要使用一個空行：

1. 類內(nèi)連續(xù)的成員之間：字段，構(gòu)造函數(shù)，方法，嵌套類，靜態(tài)初始化塊，實例初始化塊。

2. 
   
• 例外：兩個連續(xù)字段之間的空行是可選的，用于字段的空行主要用來對字段進行邏輯分組。

3. 在函數(shù)體內(nèi)，語句的邏輯分組間使用空行。

4. 類內(nèi)的第一個成員前或最后一個成員后的空行是可選的(既不鼓勵也不反對這樣做，視個人喜好而定)。

5. 要滿足本文檔中其他節(jié)的空行要求(比如3.3節(jié)：import語句)

多個連續(xù)的空行是允許的，但沒有必要這樣做(我們也不鼓勵這樣做)。

4.6.2 水平空白

除了語言需求和其它規(guī)則，并且除了文字，注釋和Javadoc用到單個空格，單個ASCII空格也出現(xiàn)在以下幾個地方：

1. 分隔任何保留字與緊隨其后的左括號(?()(如?if,forcatch等)。

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

3. 在任何左大括號前(?{)，兩個例外：

4. 
   
• @SomeAnnotation({a,b})(不使用空格)。
• String[][]x=foo;(大括號間沒有空格，見下面的Note)。

5. 在任何二元或三元運算符的兩側(cè)。這也適用于以下“類運算符”符號：

6. 
   
• 類型界限中的&(?)。
• catch塊中的管道符號(?catch(FooException|BarExceptione)。
• foreach語句中的分號。

7. 在?,:;及右括號(?))后

8. 如果在一條語句后做注釋，則雙斜杠(//)兩邊都要空格。這里可以允許多個空格，但沒有必要。

9. 類型和變量之間：List list。

10. 數(shù)組初始化中，大括號內(nèi)的空格是可選的，即?newint[]{5,6}和?newint[]{5,6}都是可以的。

“

“

Note：這個規(guī)則并不要求或禁止一行的開關(guān)或結(jié)尾需要額外的空格，只對內(nèi)部空格做要求。

4.6.3 水平對齊：不做要求

術(shù)語說明：水平對齊指的是通過增加可變數(shù)量的空格來使某一行的字符與上一行的相應字符對齊。

這是允許的(而且在不少地方可以看到這樣的代碼)，但Google編程風格對此不做要求。即使對于已經(jīng)使用水平對齊的代碼，我們也不需要去保持這種風格。

以下示例先展示未對齊的代碼，然后是對齊的代碼：

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

Tip：對齊可增加代碼可讀性，但它為日后的維護帶來問題。考慮未來某個時候，我們需要修改一堆對齊的代碼中的一行。這可能導致原本很漂亮的對齊代碼變得錯位。很可能它會提示你調(diào)整周圍代碼的空白來使這一堆代碼重新水平對齊(比如程序員想保持這種水平對齊的風格)， 這就會讓你做許多的無用功，增加了reviewer的工作并且可能導致更多的合并沖突。

4.7 用小括號來限定組：推薦

除非作者和reviewer都認為去掉小括號也不會使代碼被誤解，或是去掉小括號能讓代碼更易于閱讀，否則我們不應該去掉小括號。我們沒有理由假設(shè)讀者能記住整個Java運算符優(yōu)先級表。

4.8 具體結(jié)構(gòu)

4.8.1 枚舉類

枚舉常量間用逗號隔開，換行可選。

沒有方法和文檔的枚舉類可寫成數(shù)組初始化的格式：

private?enum?Suit?{?CLUBS,?HEARTS,?SPADES,?DIAMONDS?}

由于枚舉類也是一個類，因此所有適用于其它類的格式規(guī)則也適用于枚舉類。

4.8.2 變量聲明

4.8.2.1 每次只聲明一個變量

不要使用組合聲明，比如?inta,b;。

4.8.2.2 需要時才聲明，并盡快進行初始化

不要在一個代碼塊的開頭把局部變量一次性都聲明了(這是c語言的做法)，而是在第一次需要使用它時才聲明。局部變量在聲明時最好就進行初始化，或者聲明后盡快進行初始化。

4.8.3 數(shù)組

4.8.3.1 數(shù)組初始化：可寫成塊狀結(jié)構(gòu)

數(shù)組初始化可以寫成塊狀結(jié)構(gòu)，比如，下面的寫法都是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風格的數(shù)組聲明

中括號是類型的一部分：String[]args， 而非?Stringargs[]。

4.8.4 switch語句

術(shù)語說明：switch塊的大括號內(nèi)是一個或多個語句組。每個語句組包含一個或多個switch標簽(?caseFOO:或?default:)，后面跟著一條或多條語句。

4.8.4.1 縮進

與其它塊狀結(jié)構(gòu)一致，switch塊中的內(nèi)容縮進為2個空格。

每個switch標簽后新起一行，再縮進2個空格，寫下一條或多條語句。

4.8.4.2 Fall-through：注釋

在一個switch塊內(nèi)，每個語句組要么通過?break,continue,return或拋出異常來終止，要么通過一條注釋來說明程序?qū)⒗^續(xù)執(zhí)行到下一個語句組， 任何能表達這個意思的注釋都是OK的(典型的是用?// fall through)。這個特殊的注釋并不需要在最后一個語句組(一般是?default)中出現(xiàn)。示例：

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)

注解緊跟在文檔塊后面，應用于類、方法和構(gòu)造函數(shù)，一個注解獨占一行。這些換行不屬于自動換行(第4.5節(jié)，自動換行)，因此縮進級別不變。例如：

@Override@Nullablepublic?String?getNameIfPresent()?{?...?}

例外：單個的注解可以和簽名的第一行出現(xiàn)在同一行。例如：

@Override?public?int?hashCode()?{?...?}

應用于字段的注解緊隨文檔塊出現(xiàn)，應用于字段的多個注解允許與字段出現(xiàn)在同一行。例如：

@Partial?@Mock?DataLoader?loader;

參數(shù)和局部變量注解沒有特定規(guī)則。

4.8.6 注釋

4.8.6.1 塊注釋風格

塊注釋與其周圍的代碼在同一縮進級別。它們可以是?/* ... */風格，也可以是?// ...風格。對于多行的?/* ... */注釋，后續(xù)行必須從?*開始， 并且與前一行的?*對齊。以下示例注釋都是OK的。

/*?*?This?is??????????//?And?so???????????/*?Or?you?can?*?okay.????????????//?is?this.??????????*?even?do?this.?*/?*/

注釋不要封閉在由星號或其它字符繪制的框架里。

Tip：在寫多行注釋時，如果你希望在必要時能重新?lián)Q行(即注釋像段落風格一樣)，那么使用?/* ... */。

4.8.7 Modifiers

類和成員的modifiers如果存在，則按Java語言規(guī)范中推薦的順序出現(xiàn)。

public?protected?private?abstract?static?final?transient?volatile?synchronized?native?strictfp

命名約定

5.1 對所有標識符都通用的規(guī)則

標識符只能使用ASCII字母和數(shù)字，因此每個有效的標識符名稱都能匹配正則表達式?\w+。

在Google其它編程語言風格中使用的特殊前綴或后綴，如?name_,?mName,?s_name和?kName，在Java編程風格中都不再使用。

5.2 標識符類型的規(guī)則

5.2.1 包名

包名全部小寫，連續(xù)的單詞只是簡單地連接起來，不使用下劃線。

5.2.2 類名

類名都以?UpperCamelCase風格編寫。

類名通常是名詞或名詞短語，接口名稱有時可能是形容詞或形容詞短語?，F(xiàn)在還沒有特定的規(guī)則或行之有效的約定來命名注解類型。

測試類的命名以它要測試的類的名稱開始，以?Test結(jié)束。例如，?HashTest或?HashIntegrationTest。

5.2.3 方法名

方法名都以?lowerCamelCase風格編寫。

方法名通常是動詞或動詞短語。

下劃線可能出現(xiàn)在JUnit測試方法名稱中用以分隔名稱的邏輯組件。一個典型的模式是：test_，例如?testPop_emptyStack。并不存在唯一正確的方式來命名測試方法。

5.2.4 常量名

常量名命名模式為?CONSTANT_CASE，全部字母大寫，用下劃線分隔單詞。那，到底什么算是一個常量？

每個常量都是一個靜態(tài)final字段，但不是所有靜態(tài)final字段都是常量。在決定一個字段是否是一個常量時， 考慮它是否真的感覺像是一個常量。例如，如果任何一個該實例的觀測狀態(tài)是可變的，則它幾乎肯定不會是一個常量。只是永遠不?打算改變對象一般是不夠的，它要真的一直不變才能將它示為常量。

//?Constantsstatic?final?int?NUMBER?=?5;static?final?ImmutableList?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?mutableCollection?=?new?HashSet();static?final?ImmutableSet?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 參數(shù)名

參數(shù)名以?lowerCamelCase風格編寫。

參數(shù)應該避免用單個字符命名。

5.2.7 局部變量名

局部變量名以?lowerCamelCase風格編寫，比起其它類型的名稱，局部變量名可以有更為寬松的縮寫。

雖然縮寫更寬松，但還是要避免用單字符進行命名，除了臨時變量和循環(huán)變量。

即使局部變量是final和不可改變的，也不應該把它示為常量，自然也不能用常量的規(guī)則去命名它。

5.2.8 類型變量名

類型變量可用以下兩種風格之一進行命名：

• 單個的大寫字母，后面可以跟一個數(shù)字(如：E, T, X, T2)。
• 以類命名方式(5.2.2節(jié))，后面加個大寫的T(如：RequestT, FooBarT)。

5.3 駝峰式命名法(CamelCase)

駝峰式命名法分大駝峰式命名法(?UpperCamelCase)和小駝峰式命名法(?lowerCamelCase)。有時，我們有不只一種合理的方式將一個英語詞組轉(zhuǎn)換成駝峰形式，如縮略語或不尋常的結(jié)構(gòu)(例如”IPv6”或”iOS”)。Google指定了以下的轉(zhuǎn)換方案。

名字從?散文形式(prose form)開始:

1. 把短語轉(zhuǎn)換為純ASCII碼，并且移除任何單引號。例如：”Müller’s algorithm”將變成”Muellers algorithm”。

2. 把這個結(jié)果切分成單詞，在空格或其它標點符號(通常是連字符)處分割開。

3. 
   
• 推薦：如果某個單詞已經(jīng)有了常用的駝峰表示形式，按它的組成將它分割開(如”AdWords”將分割成”ad words”)。需要注意的是”iOS”并不是一個真正的駝峰表示形式，因此該推薦對它并不適用。

4. 現(xiàn)在將所有字母都小寫(包括縮寫)，然后將單詞的第一個字母大寫：

5. 
   
• 每個單詞的第一個字母都大寫，來得到大駝峰式命名。
• 除了第一個單詞，每個單詞的第一個字母都大寫，來得到小駝峰式命名。

6. 最后將所有的單詞連接起來得到一個標識符。

示例：

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 靜態(tài)成員：使用類進行調(diào)用

使用類名調(diào)用靜態(tài)的類成員，而不是具體某個對象或表達式。

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 段落

空行(即，只包含最左側(cè)星號的行)會出現(xiàn)在段落之間和Javadoc標記(@XXX)之前(如果有的話)。除了第一個段落，每個段落第一個單詞前都有標簽?

，并且它和第一個單詞間沒有空格。

7.1.3 Javadoc標記

標準的Javadoc標記按以下順序出現(xiàn)：@param,?@return,?@throws,?@deprecated, 前面這4種標記如果出現(xiàn)，描述都不能為空。當描述無法在一行中容納，連續(xù)行需要至少再縮進4個空格。

7.2 摘要片段

每個類或成員的Javadoc以一個簡短的摘要片段開始。這個片段是非常重要的，在某些情況下，它是唯一出現(xiàn)的文本，比如在類和方法索引中。

這只是一個小片段，可以是一個名詞短語或動詞短語，但不是一個完整的句子。它不會以?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：如果有一些相關(guān)信息是需要讀者了解的，那么以上的例外不應作為忽視這些信息的理由。例如，對于方法名?getCanonicalName， 就不應該忽視文檔說明，因為讀者很可能不知道詞語?canonical name指的是什么。

7.3.2 例外：重寫

如果一個方法重寫了超類中的方法，那么Javadoc并非必需的。

7.3.3 可選的Javadoc

對于包外不可見的類和方法，如有需要，也是要使用Javadoc的。如果一個注釋是用來定義一個類，方法，字段的整體目的或行為， 那么這個注釋應該寫成Javadoc，這樣更統(tǒng)一更友好。

推薦閱讀
程序員內(nèi)推群！北京！上海！廣州！深圳！杭州！鄭州！武漢！南京！西安！
推薦一個開源的vue+Element UI前后端分離后臺管理系統(tǒng)實戰(zhàn)！
一套簡單通用的Java后臺管理系統(tǒng)
招聘需