Google Java代碼規範

原文地址：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
1. MyLambda<String, Long, Object> lambda =
2. (String label, Long value, Object obj) -> {
3. ...
4. };
6. Predicate<String> predicate = str ->
7. 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請求”	`XmlHttpRequest`	`XMLHTTPRequest`
“新客戶ID”	`newCustomerId`	`newCustomerID`
“內部秒錶”	`innerStopwatch`	`innerStopWatch`
“在iOS上支持IPv6？	`supportsIpv6OnIos`	`supportsIPv6OnIOS`
“YouTube進口商”	`YouTubeImporter` `YoutubeImporter` *

*可接受，但不推薦。

注意：某些單詞在英語中有不明確的連字符：例如“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（使用/** ）。

非必需的Javadoc不是嚴格要求遵守第7.1.2,7.1.3和7.2節的格式化規則，但當然是建議。

傾聽心動旋律

發佈了44 篇原創文章 · 獲贊 25 · 訪問量 10萬+

私信關注

Google Java代碼規範

1簡介

1.1術語註釋

1.2指南說明

2源文件基礎

2.1文件名

2.2文件編碼：UTF-8

2.3特殊字符

2.3.1空格字符

2.3.2特殊轉義序列

2.3.3非ASCII字符

3源文件結構

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

3.2包裝聲明

3.3導入語句

3.3.1無通配符導入

3.3.2沒有線包裝

3.3.3訂購和間距

3.3.4沒有類的靜態導入

3.4類聲明

3.4.1完全一個頂級類聲明

3.4.2類內容的排序

3.4.2.1重載：從不分裂

4格式化

4.1大括號

4.1.1在可選時使用括號

4.1.2非空塊：K＆R風格

4.1.3空塊：可能簡潔

4.2塊縮進：+2個空格

4.3每行一個語句

4.4列限制：100

4.5線包裝

4.5.1打破的地方

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

4.6空白

4.6.1垂直空白

4.6.2水平空白

4.6.3水平對齊：從不需要

4.7分組括號：推薦

4.8特定構建體

4.8.1枚舉類

4.8.2變量聲明

4.8.2.1每個聲明一個變量

4.8.2.2需要時聲明

4.8.3數組

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

4.8.3.2沒有C樣式數組聲明

4.8.4切換語句

4.8.4.1縮進

4.8.4.2通過：評論

4.8.4.3 default情況存在

4.8.5註釋

4.8.6評論

4.8.6.1塊註釋樣式

4.8.7修飾符

4.8.8數字文字

5命名

5.1所有標識符共有的規則

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

5.2.1包名稱

5.2.2類名

5.2.3方法名稱

5.2.4常量名稱

5.2.5非常量字段名稱

5.2.6參數名稱

5.2.7局部變量名

5.2.8類型變量名

5.3駱駝情況：定義

6編程實踐

6.1@Override ：始終使用

6.2捕獲異常：不被忽略

6.3靜態成員：使用類合格

6.4終化劑：未使用

7 Javadoc

7.1格式化

7.1.1一般形式

7.1.2段落

7.1.3條款

7.2摘要片段

7.3其中使用Javadoc

4.8.4.3 `default`情況存在

6.1`@Override` ：始終使用