[轉載] Google Java代碼規范

參考鏈接：使用Java計算文本文件txt中的行數/單詞數/字符數和段落數

原文地址：https://google.github.io/styleguide/javaguide.html

GIthub上GoogleCode風格的配置文件（支持Eclipse IDE和IntelliJ IDE）：https://github.com/codeset/google-java-styleguide

1簡介

本文檔作為Java編程語言中源代碼的Google編碼標準的完整定義。當且僅當它遵守本文中的規則時，Java源文件被描述為在Google Style中。

與其他編程風格指南一樣，所涵蓋的問題不僅包括格式化的美學問題，也包括其他類型的約定或編碼標準。但是，本文檔主要關注我們普遍遵循的快速規則，并避免提供不可明確強制執行的建議（無論是通過人工還是工具）。

1.1術語注釋

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

術語類被包含性地用于表示“普通”類，枚舉類，接口或注釋類型（ @interface ）。術語成員（類的）包含地用于表示嵌套類，字段，方法或構造函數 ;即除了初始化器和注釋之外的類的所有頂級內容。術語注釋總是指實現注釋。我們不使用短語“文檔注釋”，而是使用通用術語“Javadoc”。

其他“術語說明”將偶爾出現在整個文檔中。

1.2指南說明

本文檔中的示例代碼是非規范的。也就是說，雖然示例是在Google風格，但它們可能不會說明代表代碼的唯一時尚的方式。示例中所做的可選格式選擇不應作為規則強制執行。

2源文件基礎

2.1文件名

源文件名由其包含的頂級類（其中包含正好一個）的區分大小寫的名稱，以及.java擴展名組成。

2.2文件編碼：UTF-8

源文件以UTF-8編碼。

2.3特殊字符

2.3.1空格字符

除了行終止符序列， ASCII水平空格字符（ 0x20 ）是在源文件中任何位置出現的唯一的空格字符。這意味著：

字符串和字符文字中的所有其他空白字符都將被轉義。制表符不用于縮進。

2.3.2特殊轉義序列

對于具有特殊轉義序列（ \b ，\t ，\n ，\f ，\r ，\" ，\'和\\ ）的任何字符，使用該序列而不是相應的八進制Unicode（例如\u000a ）轉義。

2.3.3非ASCII字符

對于剩余的非ASCII字符，使用實際的Unicode字符（例如∞ ）或等效的Unicode轉義（例如\u221e ）。選擇僅取決于哪些使得代碼更容易閱讀和理解，盡管Unicode轉義字符串字面值和注釋強烈阻止。

提示：在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良好：對不可打印字符使用轉義，如有必要，請注釋。

提示：不要因為某些程序可能無法正確處理非ASCII字符而使您的代碼變得不可讀。如果這應該發生，那些程序被打破，它們必須是固定的。

3源文件結構

?源文件由以下順序組成：

?許可或版權信息（如果存在）軟件包語句導入語句完全一個頂級類

正好一個空白線分隔存在的每個部分。

3.1許可或版權信息（如果存在）

如果許可證或版權信息屬于文件，則它屬于此處。

3.2包裝聲明

包語句不是線包裝。列限制（第4.4節，列限制：100 ）不適用于包語句。

3.3導入語句

3.3.1無通配符導入

不使用靜態或其他方式的通配符導入。

3.3.2沒有線包裝

導入語句不是線包裝的。列限制（第4.4節，列限制：100 ）不適用于import語句。

3.3.3訂購和間距

導入順序如下：

在單個塊中的所有靜態導入。所有非靜態導入在單個塊中。

如果存在靜態和非靜態導入，則單個空白行分隔兩個塊。 import語句之間沒有其他空行。

在每個塊中，導入的名稱以ASCII排序順序顯示。（注意：這與以ASCII排序順序的import 語句不同，因為'。'排在';'前面）。

3.3.4沒有類的靜態導入

靜態導入不用于靜態嵌套類。它們以正常進口進口。

3.4類聲明

3.4.1完全一個頂級類聲明

每個頂級類都駐留在自己的源文件中。

3.4.2類內容的排序

為類的成員和初始化器選擇的順序可以對可學習性有很大的影響。然而，沒有一個正確的方法來做到這一點; 不同的類可以以不同的方式對其內容進行排序。

重要的是每個類使用一些邏輯順序，維護者可以解釋如果問。例如，新方法不僅習慣性地添加到類的末尾，因為這將產生“按照添加日期的順序”排序，這不是邏輯排序。

3.4.2.1重載：從不分裂

當一個類有多個構造函數或者多個同名的方法時，這些順序出現，中間沒有其他代碼（甚至不是私有成員）。

4格式化

術語注意：塊狀構造指的是類，方法或構造函數的主體。注意，通過關于數組初始化器的第4.8.3.1節，任何數組初始化器都可以被視為塊狀構造。

4.1大括號

4.1.1在可選時使用括號

大括號與if ，else ，for ，do和while語句一起使用，即使主體為空或僅包含單個語句。

4.1.2非空塊：K＆R風格

大括號遵循Kernighan和Ritchie風格（“ 埃及括號 ”）用于非空塊和塊狀結構：

在大括號前沒有換行符。開頭大括號后的換行符。換行前的換行。關閉大括號后的換行符，僅當該大括號終止語句或終止方法，構造函數或命名類的主體時。例如，如果后面跟著else或逗號，那么大括號后面沒有換行符。

例子：

? ?[java]?

? ?view plain

? ? copy

? ?

?return () -> {? ? while (condition()) {? ? ? method();? ? }? };? ? return new MyClass() {? ? @Override public void method() {? ? ? if (condition()) {? ? ? ? try {? ? ? ? ? something();? ? ? ? } catch (ProblemException e) {? ? ? ? ? recover();? ? ? ? }? ? ? } else if (otherCondition()) {? ? ? ? somethingElse();? ? ? } else {? ? ? ? lastThing();? ? ? }? ? }? };??

枚舉類的一些例外在第4.8.1節“枚舉類”中給出。

4.1.3空塊：可能簡潔

空塊或塊狀構造可以是K＆R樣式（如第4.1.2節所述）。或者，它可以在打開后立即關閉，在（{} ）之間沒有字符或換行符，除非它是多塊語句的一部分（直接包含多個塊：if/else或try/catch/finally）。

例子：

? ?[java]?

? ?view plain

? ? copy

? ?

?// This is acceptable? ? ?void doNothing() {}? ? ?// This is equally acceptable? ?void doNothingElse() {? ?}??

? ?[java]?

? ?view plain

? ? copy

? ?

?// This is not acceptable: No concise empty blocks in a multi-block statement? ?try {? ? ?doSomething();? ?} catch (Exception e) {}??

4.2塊縮進：+2個空格

每次打開新的塊或塊狀構造時，縮進增加兩個空格。當塊結束時，縮進返回到上一縮進級別。縮進級別適用于整個塊中的代碼和注釋。（請參見第4.1.2節“ 非空塊：K＆R Style”中的示例。）

4.3每行一個語句

每個語句后面都有換行符。

4.4列限制：100

Java代碼的列限制為100個字符。除非如下所述，否則超過此限制的任何行都必須被換行，如第4.5節“ 換行”中所述。

例外：

無法遵守列限制的行（例如，Javadoc中的長URL或長JSNI方法引用）。package和import語句（見第3.2節包語句和3.3導入語句）。注釋中的命令行可以剪切并粘貼到shell中。

4.5線包裝

術語注意：當可能合法占用單個行的代碼被分為多行時，此活動稱為行換行。

沒有全面的，確定性的公式，顯示每種情況下如何包裝。通常有幾種有效的方法來換行同一段代碼。

注意：雖然換行的典型原因是為了避免溢出列限制，即使在事實上符合列限制的代碼也可能由作者自行決定。

提示：提取方法或局部變量可以解決問題，而不需要換行。

4.5.1打破的地方

線包裝的主要指令是：更喜歡在更高的語法層面打破。也：

當在非賦值運算符處斷開一行時，中斷在符號之前。（請注意，這與其他語言（例如C ++和JavaScript）在Google樣式中使用的做法不同）。

? 這也適用于以下“類似運算符”的符號：

? ? 點分隔符（ . ）方法引用（::）的兩個冒號類型邊界中的<TextendsFoo&Bar>符號（<TextendsFoo&Bar> ）在catch塊中的一個管道（ catch (FooException|BarException e) ）。當一個行在賦值操作符中斷時，中斷通常出現在符號之后，但是任何一種方式都是可以接受的。

? 這也適用于增強型for （“foreach”）語句中的“賦值運算符”冒號。方法或構造函數名稱附加到它后面的開括號（ ( ））。逗號（ , ）保持附加到它前面的令牌。在lambda中，一行從不會被折斷，除了如果lambda的主體由單個非支持表達式組成，則可能會在箭頭之后立即出現中斷。例子：

? ?

? ??

? ? ?[java]?

? ? ?view plain

? ? ? copy

? ? ?

? ??

? ?

? ?MyLambda<String, Long, Object> lambda =? ? ? (String label, Long value, Object obj) -> {? ? ? ? ? ...? ? ? };? ? Predicate<String> predicate = str ->? ? ? longExpressionInvolving(str);??

注意：換行的主要目標是具有清除代碼，不一定代碼適合最小的行數。

4.5.2縮進連續線至少+4個空格

當換行時，第一行（每個連續行）后面的每一行從原始行縮進至少+4。

當存在多個連續線時，根據需要，壓痕可以變化超過+4。一般來說，當且僅當它們以句法并行元素開頭時，兩個連續行使用相同的縮進級別。

關于水平對齊的第4.6.3節闡述了使用可變數量的空間將某些令牌與先前的行對齊的不鼓勵做法。

4.6空白

4.6.1垂直空白

將顯示一個空白行：

在類的連續成員或初始化器之間：字段，構造函數，方法，嵌套類，靜態初始化器和實例初始化器。

? 異常：兩個連續字段之間的空行（它們之間沒有其他代碼）是可選的。這樣的空白行根據需要用于創建字段的邏輯分組。異常：枚舉常量之間的空行在第4.8.1節中介紹。在語句之間，根據需要將代碼組織成邏輯子部分。可選地在第一個成員或初始化程序之前，或在類的最后一個成員或初始化程序之后（既不鼓勵也不鼓勵）。根據本文檔其他部分的要求（如第3節，源文件結構和第3.3節，導入語句）。

允許多個連續的空行，但不需要（或鼓勵）。

4.6.2水平空白

除了語言或其他樣式規則所要求的之外，除了文字，注釋和Javadoc之外，單個ASCII空間也僅出現在以下位置。

將任何保留字（例如if ，for或catch ）從該行后面的開括號（( ））中分離將任何保留字（例如else或catch ）與該行上的關閉大括號（} ）分隔開在任何打開的大括號（ { ）之前，有兩個例外：

? @SomeAnnotation({a, b}) （不使用空格）String[][] x={{"foo"}};（{{下面第8項）之間不需要空格，在任何二進制或三元運算符的兩側。這也適用于以下“類似運算符”的符號：

? 連接符類型的連接<TextendsFoo&Bar> ：<TextendsFoo&Bar>用于處理多個異常的catch塊的管道： catch (FooException|BarException e)冒號（：）在增強型for （“foreach”）語句中lambda表達式中的箭頭： (String str)-> str.length()但不是

? 一個方法引用的兩個冒號（::），它寫得像Object::toString點分隔符（ . ），它寫作object.toString()后,:;或右括號（) ）在開始結束行注釋的雙斜線（ // ）的兩側。這里，允許多個空格，但不是必需的。在一個聲明的類型和變量之間： List<String> list可選只在數組初始值設定符的兩個大括號內

? newint[]{5,6}和newint[]{5,6}都是有效的

此規則從不解釋為在行的開始或結束處要求或禁止額外的空間;

它只涉及內部空間。

4.6.3水平對齊：從不需要

術語注意：水平對齊是在代碼中添加可變數量的附加空間的做法，目的是使某些令牌直接顯示在之前行上的某些其他令牌下方。

這種做法是允許的，但Google風格從不需要。甚至不需要在已經使用的地方保持水平對準。

這里是一個沒有對齊的例子，然后使用對齊：

? ?[java]?

? ?view plain

? ? copy

? ?

?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??

提示：

對齊可以幫助可讀性，但它會為以后的維護帶來問題。

考慮一個需要觸摸只有一行的未來變化。

這種變化可能會使以前令人愉快的格式化失敗，這是允許的。

更頻繁地，它提示編碼器（也許你）調整附近線上的空白，可能觸發級聯系列的重新格式化。

那一行的變化現在有一個“爆炸半徑”。

這可能在最壞的情況下導致無意義的繁忙工作，但最多仍會破壞版本歷史信息，減慢審閱者和加劇合并沖突。

4.7分組括號：推薦

可選的分組括號只有在作者和審稿人同意沒有合理的機會，沒有他們的代碼將被誤解，他們也不會使代碼更容易閱讀。假設每個讀取器都具有存儲的整個Java運算符優先級表是不合理的。

4.8特定構建體

4.8.1枚舉類

在遵循枚舉常量的每個逗號后，換行符是可選的。還允許附加空行（通常只有一個）。這是一個可能性：

? ?[java]?

? ?view plain

? ? copy

? ?

?private enum Answer {? ? ? YES {? ? ? @Override public String toString() {? ? ? ? return "yes";? ? ? }? ? },? ? ? NO,? ? MAYBE? }??

沒有方法和沒有文檔的常量的枚舉類可以可選地被格式化為數組初始化器（見關于數組初始化器的第4.8.3.1節）。

? ?[java]?

? ?view plain

? ? copy

? ?

?privete enum Clothes{CLUBS，HEARTS，SPADES，DIAMONDS}??

由于枚舉類是類，因此適用于格式化類的所有其他規則。

4.8.2變量聲明

4.8.2.1每個聲明一個變量

每個變量聲明（字段或本地）只聲明一個變量：聲明如int a, b;不使用。

4.8.2.2需要時聲明

局部變量不習慣地在它們的包含塊或塊狀構造的開始處聲明。相反，局部變量被聲明為接近它們首次使用的點（在原因內），以最小化它們的范圍。局部變量聲明通常具有初始化器，或者在聲明之后立即初始化。

4.8.3數組

4.8.3.1數組初始化器：可以是“塊狀”

任何數組初始化器可以可選地被格式化為好像它是“塊狀構造”。例如，以下都是有效的（不是詳盡的列表）：

? ?[java]?

? ?view plain

? ? copy

? ?

?new int[] {? ? ? ? ? ?new int[] {? ? 0, 1, 2, 3? ? ? ? ? ? 0,? }? ? ? ? ? ? ? ? ? ? ? ?1,? ? ? ? ? ? ? ? ? ? ? ? ? 2,? new int[] {? ? ? ? ? ? ?3,? ? 0, 1,? ? ? ? ? ? ? ?}? ? 2, 3? }? ? ? ? ? ? ? ? ? ? ?new int[]? ? ? ? ? ? ? ? ? ? ? ? ? ? {0, 1, 2, 3}??

4.8.3.2沒有C樣式數組聲明

方括號形成類型的一部分，而不是變量： String[] args ，而不是String args[] 。

4.8.4切換語句

術語注意：交換機塊的大括號內是一個或多個語句組。每個語句組由一個或多個開關標簽（無論是caseFOO:或default: ：）組成，后跟一個或多個語句。

4.8.4.1縮進

與任何其他塊一樣，開關塊的內容縮進+2。

在切換標簽之后，有一個換行符，縮進級別增加+2，就像打開一個塊一樣。以下開關標簽返回到上一縮進級別，如同一個塊已關閉。

4.8.4.2通過：評論

在開關塊內，每個語句組都會突然終止（使用break ，continue ，return或thrown異常），或者標記有注釋，指示執行將繼續或可能繼續到下一個語句組。任何傳達墮落想法的評論都是足夠的（通常// fall through ）。在開關組的最后一個語句組中不需要此特殊注釋。例：

? ?[java]?

? ?view plain

? ? copy

? ?

?switch (input) {? ? case 1:? ? case 2:? ? ? prepareOneOrTwo();? ? ? // fall through? ? case 3:? ? ? handleOneTwoOrThree();? ? ? break;? ? default:? ? ? handleLargeNumber(input);? }??

注意，在

case1:

之后不需要注釋，只在語句組的末尾。

4.8.4.3 default情況存在

每個switch語句包括一個default語句組，即使它不包含代碼。

4.8.5注釋

應用于類，方法或構造函數的注釋立即出現在文檔塊之后，并且每個注釋都列在其自己的行（即每行一個注釋）上。這些換行符不構成換行（第4.5節，換行），因此縮進級別不會增加。例：

? ?[java]?

? ?view plain

? ? copy

? ?

?@Override? @Nullable? public String getNameIfPresent() { ... }??

異常：

單個

無參數注釋

可以

改為與簽名的第一行一起出現，例如：

? ?[java]?

? ?view plain

? ? copy

? ?

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

應用于字段的注釋也會立即出現在文檔塊之后，但在這種情況下，?

多個

注釋（可能已參數化）可能會列在同一行上;

例如：

? ?[java]?

? ?view plain

? ? copy

? ?

?@Partial @Mock DataLoader loader;??

沒有關于參數，局部變量或類型的注釋格式化的具體規則。

4.8.6評論

本節討論實現注釋。 Javadoc在第7節Javadoc中單獨解決。

任何換行符之前可以有任意空格，然后是實現注釋。這樣的注釋使該行非空白。

4.8.6.1塊注釋樣式

塊注釋縮進到與周圍代碼相同的級別。它們可以是/* ... */ style或// ...樣式。對于多行/* ... */注釋，后續行必須以*與上一行的*對齊開始。

? ?[java]?

? ?view plain

? ? copy

? ?

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

注釋不包含在用星號或其他字符繪制的框中。

提示：在編寫多行注釋時，如果您希望自動代碼格式化程序在必要時重新換行（段落樣式），請使用/* ... */樣式。大多數格式化程序不會在// ...樣式注釋塊中重新換行。

4.8.7修飾符

類和成員修飾符（如果存在）按照Java語言規范建議的順序顯示：

? ?[java]?

? ?view plain

? ? copy

? ?

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

4.8.8數字文字

long整數文字使用大寫L后綴，從不小寫（以避免與數字1混淆）。例如，3000000000L而不是3000000000l 。

5命名

5.1所有標識符共有的規則

標識符只使用ASCII字母和數字，并且在下面指出的少數情況下，下劃線。因此，每個有效的標識符名稱由正則表達式\w+匹配。

在Google Style中，特殊的前綴或后綴，如在示例name_ ，mName ，s_name和kName中看到的，不使用。

5.2按標識符類型劃分的規則

5.2.1包名稱

包名稱都是小寫，連續的單詞連接在一起（無下劃線）。例如， com.example.deepspace ，而不是com.example.deepSpace或com.example.deep_space 。

5.2.2類名

類名寫在UpperCamelCase中。

類名通常是名詞或名詞短語。例如， Character或ImmutableList 。接口名稱也可以是名詞或名詞短語（例如，List ），但有時可以是形容詞或形容詞短語（例如，Readable ）。

沒有特定的規則，甚至沒有成熟的慣例為命名注釋類型。

測試類從它們正在測試的類的名稱開始命名，并以Test結束。例如，HashTest或HashIntegrationTest 。

5.2.3方法名稱

方法名稱寫在lowerCamelCase中。

方法名稱通常是動詞或動詞短語。例如，sendMessage或stop 。

下劃線可能出現在JUnit 測試方法名稱中以分隔名稱的邏輯組件。一個典型的模式是test <MethodUnderTest> _ <state> ，例如testPop_emptyStack 。沒有一個正確的方法來命名測試方法。

5.2.4常量名稱

常量名稱使用CONSTANT_CASE ：所有大寫字母，用下劃線分隔的單詞。但什么是常數，究竟是什么？

常數是靜態最終字段，其內容是不可變的，并且其方法沒有可檢測的副作用。這包括基元，字符串，不可變類型和不可變類型的不可變集合。如果任何實例的observable狀態可以改變，它不是一個常量。只是打算從來不改變對象是不夠的。例子：

? ?[java]?

? ?view plain

? ? copy

? ?

?// Constants? static final int NUMBER = 5;? static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");? static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);? 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 ImmutableMap<String, SomeMutableType> mutableValues =? ? ? ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);? static final Logger logger = Logger.getLogger(MyClass.getName());? static final String[] nonEmptyArray = {"these", "can", "change"};??

這些名稱通常是名詞或名詞短語。

5.2.5非常量字段名稱

非常量字段名（靜態或其他）寫在lowerCamelCase中。

這些名稱通常是名詞或名詞短語。例如，computedValues或index 。

5.2.6參數名稱

參數名稱寫在lowerCamelCase中。

應該避免公共方法中的單字符參數名稱。

5.2.7局部變量名

局部變量名寫在lowerCamelCase中。

即使最終和不可變的局部變量不被認為是常量，并且不應該被定型為常量。

5.2.8類型變量名

每個類型變量都以兩種樣式之一命名：

單個大寫字母，可選后跟單個數字（例如E ，T ，X ，T2 ）用于類的形式的名稱（見第5.2.2節，類名），后跟大寫字母T （示例：RequestT，FooBarT ）。

5.3駱駝情況：定義

有時，有一個以上的合理方式將英語短語轉換為駱駝情況，例如當首字母縮略詞或不尋常的結構，如“IPv6”或“iOS”存在。為了提高可預測性，Google Style指定以下（幾乎）確定性方案。

從名稱的散文形式開始：

將短語轉換為純ASCII并刪除任何省略號。例如，“Müller算法”可能變成“Muellers算法”。將此結果劃分為單詞，分割為空格和任何剩余的標點符號（通常為連字符）。

? 推薦：如果任何字詞在常用的情況下已經具有常規的駝峰盒外觀，請將其分為其組成部分（例如，“AdWords”成為“廣告字詞”）。注意，諸如“iOS”這樣的詞本身不是真正的駱駝情況;它違反任何慣例，因此本建議不適用。現在小寫一切（包括首字母縮略詞），然后大寫只有第一個字符：

? ...每個字，產生上駱駝殼，或...每個字除了第一個，產生較低的駝峰盒最后，將所有單詞連接成單個標識符。

注意，原始單詞的殼體幾乎完全被忽略。例子：

散文形式正確不正確“XML HTTP請求”XmlHttpRequestXMLHTTPRequest“新客戶ID”newCustomerIdnewCustomerID“內部秒表”innerStopwatchinnerStopWatch“在iOS上支持IPv6？supportsIpv6OnIossupportsIPv6OnIOS“YouTube進口商”YouTubeImporterYoutubeImporter *?

*可接受，但不推薦。

注意：某些單詞在英語中有不明確的連字符：例如“nonempty”和“non-empty”都是正確的，所以方法名稱checkNonempty和checkNonEmpty也是正確的。

6編程實踐

6.1@Override ：始終使用

一個方法在合法時用@Override注釋標記。這包括重寫超類方法的類方法，實現接口方法的類方法和重定義超接口方法的接口方法。

異常：當父方法為@Deprecated時，可以省略@Deprecated 。

6.2捕獲異常：不被忽略

除非如下所述，在響應捕獲的異常時不執行任何操作是非常不正確的。（典型的響應是記錄它，或者如果它被認為是“不可能”，將其重新拋出為一個AssertionError 。）

當在catch塊中沒有采取任何行動是真正合適的時候，這是合理的原因在注釋中解釋。

? ?[java]?

? ?view plain

? ? copy

? ?

?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

開始，

則

可以忽略捕獲的異常而不進行注釋。

以下是一個非常常見的用于確保測試中的代碼確實拋出了預期類型的??異常的習語，因此在此不需要注釋。

? ?[java]?

? ?view plain

? ? copy

? ?

?try {? ? emptyStack.pop();? ? fail();? } catch (NoSuchElementException expected) {? }??

6.3靜態成員：使用類合格

當對靜態類成員的引用必須限定時，它將使用該類的名稱限定，而不是該類的類型的引用或表達式。

Foo aFoo = ...;

Foo.aStaticMethod(); // good

aFoo.aStaticMethod(); // bad

somethingThatYieldsAFoo().aStaticMethod(); // very bad

6.4終化劑：未使用

覆蓋Object.finalize是非常罕見的。

提示：不要這樣做。如果你絕對必須，首先閱讀并理解有效的Java項目7，“避免終結者”，非常仔細，然后不這樣做。

7 Javadoc

7.1格式化

7.1.1一般形式

Javadoc塊的基本格式如下例所示：

? ?[java]?

? ?view plain

? ? copy

? ?

?/**? * Multiple lines of Javadoc text are written here,? * wrapped normally...? */? public int method(String p1) { ... }??

...或在此單行示例中：

? ?[java]?

? ?view plain

? ? copy

? ?

?/** An especially short bit of Javadoc. */??

基本形式總是可以接受的。?

當不存在at-clause時，單行形式可以被替換，并且Javadoc塊（包括注釋標記）的整體可以適合在單個行上。

7.1.2段落

一個空行（即，僅包含對齊的前導星號（ * ）的行）出現在段落之間，并在“at-clause”組（如果存在）之前。每個段落，但第一個在緊接第一個單詞之前有<p>后面沒有空格。

7.1.3條款

任何使用的標準“at- @deprecated ”都出現在@param@deprecated ，@return@deprecated ， @return ， @param@deprecated這些@deprecated ，并且這四種類型不會出現空描述。當at-clause不適合單個行時，連續行從@的位置縮進四（或更多）個空格。

7.2摘要片段

每個Javadoc塊以簡短摘要片段開頭。這個片段非常重要：它是出現在某些上下文中的文本的唯一部分，例如類和方法索引。

這是一個片段 - 一個名詞短語或動詞短語，而不是一個完整的句子。它不以A {@code Foo} is a...開頭A {@code Foo} is a... ，或者This method returns... ，也不會形成一個完整的命令句，如Save the record.。然而，片段被大寫和標點，好像它是一個完整的句子。

提示：常見的錯誤是以/** @return the customer ID */編寫簡單的Javadoc。這是不正確的，應該更改為/** Returns the customer ID. *//** Returns the customer ID. */ 。

7.3其中使用Javadoc

至少，Javadoc存在于每個public類以及這種類的每個public或protected成員，除了下面列出的一些例外。

還可能存在其他Javadoc內容，如第7.3.4節“ 非必需Javadoc”中所述。

7.3.1異常：自明的方法

Javadoc對于“簡單的，明顯的”方法（如getFoo是可選的，在真正和真正沒有什么別的值得說，但“返回foo”。

重要提示：引用此例外是不恰當的，因為省略了典型讀者可能需要知道的相關信息。例如，對于名為getCanonicalName的方法，不要省略其文檔（只有/** Returns the canonical name. */ ），如果典型的讀者可能不知道術語“canonical name”手段！

7.3.2異常：覆蓋

Javadoc并不總是出現在覆蓋超類型方法的方法上。

7.3.4非必需Javadoc

其他類和成員根據需要或期望具有Javadoc。

每當實現注釋用于定義類或成員的總體目的或行為時，該注釋將改為寫為Javadoc（使用/** ）。