Google Java Style 指南

**

1 前言

**

本文檔參考并翻譯自Google Java Style Guide。Google風格官方使用的是2個空格的縮進，國内常用的縮進為4個空格，是以此文檔改為4個空格。同理，自動換行Google是+4個，此處為+8個，switch塊縮進Google是2個，此處為4個。

本文檔作為Java™程式設計語言中源代碼的Google編碼标準的完整定義。 當且僅當它遵守本文中的規則時，Java源檔案才被稱為遵循Google Style。

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

1.1 術語說明

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

術語 class 可表示一個普通類、枚舉類、接口或是注解類型（@interface）。

術語 member （類的）可表示内部類、變量、方法或是構造函數；即除了初始化代碼塊與注釋以外的類的所有頂級内容。

術語 comment 通常用于表示實作的注釋（implementation comments），我們不使用“documentation comments”，而是用“Javadoc”。

其他的“術語說明”則會在後面的文檔偶爾出現。

1.2 指南說明

本文檔中的示例代碼是非規範的。也就是說，雖然示例遵循Google Style，但其并不代表這就是展現代碼優雅的唯一方式。示例中所做的可選格式的選擇不應視為規則強制執行。

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、"、'及\），我們使用它的轉義序列，而不是相應的八進制(比如\012)或Unicode(比如\u000a)轉義。

2.3.3 非ASCII字元

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

提示： 在使用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字元而讓你的代碼可讀性變差。當程式無法正确處理非ASCII字元時，它自然無法正确運作，也就需要修複了。

3 源檔案結構

一個源檔案按順序包含：

許可證或版權資訊（如需）

package語句

import語句

有且僅有一個的頂級類

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

3.1 許可證或版權資訊（如需）

如果一個檔案包含許可證或版權資訊，那麼它應當被放在檔案最前面。

3.2 package語句

package語句不換行，列限制（章節4.4）并不适用于package語句。

3.3 import語句

3.3.1 import不要使用通配符

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

3.3.2 不要換行

import語句不換行，列限制(章節4.4)并不适用于import語句。

3.3.3 順序和間距

導入順序如下：

所有的靜态導入獨立成組。

所有的非靜态導入獨立成組。

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

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

3.3.4 沒有靜态導入的類

靜态導入不能用于靜态内部類。它們以普通導入方式導入。

3.4 類聲明

3.4.1 有且僅有一個頂級類

每個頂級類都駐留在自己的源檔案中。

3.4.2 類成員順序

類的成員順序對易學性有很大的影響，但這也不存在唯一的通用法則。不同的類對成員的排序可能是不同的。

最重要的一點，每個類應該以某種邏輯去排序它的成員，維護者應該要能解釋這種排序邏輯。比如，新的方法不能總是習慣性地添加到類的結尾，因為這樣就是按時間順序而非某種邏輯來排序的。

3.4.2.1 區塊劃分

當一個類有多個構造函數或者多個同名的方法時，它們順序出現，并且中間沒有其他代碼（包括私有member）。

4 格式化

術語說明：塊狀結構（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）：

左大括号前不換行

左大括号後換行

右大括号前換行

右大括号後換行，隻有右大括号是一個語句、函數體或類的終止，則右大括号後換行。例如，如果後面跟着else或逗号，那麼右大括号後面不換行。

示例：

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給出了enum類的一些例外。

4.1.3 空塊：可以用簡潔版本

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

示例：

// 這是可以接受的

void doNothing() {}

// 這是同樣可以接受的

void doNothingElse() {

}

// 這是不可接受的: 多塊語句中沒有簡明的空塊

try {

doSomething();

} catch (Exception e) {}

4.2 塊縮進：4個空格

每次打開新的塊或塊狀構造時，縮進增加4個空格。當塊結束時，縮進傳回到上一縮進級别。縮進級别适用于整個塊中的代碼和注釋。(詳見章節4.1.2中的代碼示例)

4.3 一行一個語句

每個語句後要換行。

4.4 列限制：100

Java代碼的列限制為100個字元。除非如下所述，否則超過此限制的任何行都必須被換行，詳見章節4.5所述。

例外：

不可能滿足列限制的行(例如，Javadoc中的一個長URL，或是一個長的JSNI方法參考)。

package和import語句(見章節3.2和章節3.3)。

注釋中那些可能被剪切并粘貼到shell中的指令行。

4.5 自動換行

術語說明： 當合法占用單行的代碼被分為多行時，我們稱之為自動換行(line-wrapping)。

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

說明： 雖然自動換行的典型原因是為了避免溢出列限制，但事實上符合列限制的代碼也可以自動換行，這由代碼作者自行決定。

提示： 通過提取方法或局部變量可以解決不得不自動換行的問題。

4.5.1 從哪裡斷開

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

如果在非指派運算符處斷開，那麼在該符号前斷開。（注意：這一點與 Google 其它語言的程式設計風格不同，如 C++ 和 JavaScript。）這條規則也适用于以下"類運算符"符号：

點分隔符（.）

一個方法引用的兩個冒号（::）

類型界限中的 &（<T extends Foo & Bar>）

捕獲塊中的管道符号（catch (FooException | BarException e)）。

如果在指派運算符處斷開，通常在該符号後斷開，但是在符号之前也是可以接受的。

這條規則也适用于foreach語句中的冒号。

方法名或構造函數名與左括号（(）留在同一行。

逗号（,）與其前面的内容留在同一行。

在Lambda表達式中，一行從不會被斷開，除了如果Lambda表達式的主體由單個非支援表達式組成，則可能會在箭頭之後立即出現斷開。示例：

MyLambda<String, Long, Object> lambda =

(String label, Long value, Object obj) -> {

…

};

Predicate predicate = str ->

longExpressionInvolving(str);

說明： 自動換行的主要目的是為了使代碼更為清晰，但對代碼要求行數越少越好，則自動換行就沒有必要了。

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

自動換行時，第一行後面的每一行（每個連續行）從原始行縮進至少增加8個空格。

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

章節4.6.3水準對齊一節中指出，不鼓勵使用可變數目的空格來對齊前面行的符号。

4.6 空白

4.6.1 垂直空白

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

類内連續的成員之間：字段，構造函數，方法，嵌套類，靜态初始化塊，執行個體初始化塊。

例外： 兩個連續字段之間的空行（在它們之間沒有其他代碼）是可選的。這樣的空白行根據需要用于建立字段的邏輯分組。

例外： 枚舉常量之間的空行，章節4.8.1将介紹。

在函數體内，語句的邏輯分組間使用空行。

類内的第一個成員前或最後一個成員後的空行是可選的。（既不鼓勵也不反對這樣做，視個人喜好而定。）

要滿足本文檔中其他節的空行要求。（比如章節3：源檔案結構及章節3.3：import語句）

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

4.6.2 水準空白

除了語言需求和其它規則，并且除了文字，注釋和Javadoc用到單個空格，單個ASCII空格僅出現在以下幾個地方：

分隔任何保留字（如：if、for及catch）與緊随其後的左括号（(）。

分隔任何保留字（如：else或catch）與其前面的右大括号（}）。

在任何左大括号前（{），兩個例外：

@SomeAnnotation({a, b})（不使用空格）

String[][] x = {{“foo”}};（兩個大括号之間無空格）

在任何二進制或三元運算符的兩側。這也适用于以下"類運算符"符号：

類型界限中的&符：<T extends Foo & Bar>

catch塊中的管道符号：catch (FooException | BarException e)

foreach語句中的冒号（:）。

在, : ;及右括号（)）後

如果在一條語句後做注釋，則雙斜杠（//）兩邊都要空格。這裡可以允許多個空格，但沒有必要。

類型和變量之間：List list

在數組初始值設定符的兩個大括号内可選

new int[] {5, 6}與new int[] { 5, 6 }都可行

此規則不應了解為在行的開始或結束處要求或禁止額外的空格; 它隻涉及行的内部空格。

4.6.3 水準對齊：不做要求

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

這是允許的，但Google程式設計風格對此不做要求。即使對于已經使用水準對齊的代碼，我們也不需要去保持這種風格。

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

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

說明： 對齊可增加代碼可讀性，但它為日後的維護帶來問題。考慮未來某個時候，我們需要修改一堆對齊的代碼中的一行。

這可能導緻原本很漂亮的對齊代碼變得錯位。很可能它會提示你調整周圍代碼的空白來使這一堆代碼重新水準對齊(比如程式員想保持這種水準對齊的風格)。這就會讓你做許多的無用功，增加了reviewer的工作并且可能導緻更多的合并沖突。

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

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

4.8 具體結構

4.8.1 枚舉類

枚舉常量間用逗号隔開，換行可選。 還允許附加空行（通常隻有一個）。 這是一個樣例：

private enum Answer {

YES {

@Override public String toString() {

return “yes”;

}

},

NO,
MAYBE
           

}

沒有方法和文檔的枚舉類可寫成數組初始化的格式（詳見章節4.8.3.1）。

private enum Suit { 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 數組初始化：可寫成塊狀結構

數組初始化可以寫成塊狀結構，比如，下面的寫法都是可行的：

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風格的數組聲明

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

4.8.4 switch語句

術語說明： switch塊的大括号内是一個或多個語句組。每個語句組包含一個或多個switch标簽(case FOO:或default:)，後面跟着一條或多條語句（最後一個語句組後面沒有語句或者跟着多條語句）。

4.8.4.1 縮進

與其它塊狀結構一緻，switch塊中的内容縮進為4個空格。每個switch标簽後新起一行，再縮進4個空格，寫下一條或多條語句。

4.8.4.2 Fall-through：注釋

在一個switch塊内，每個語句組要麼通過break、continue、return或抛出異常來終止，要麼通過一條注釋來說明程式将繼續執行到下一個語句組， 任何能表達這個意思的注釋都是可行的(典型的是用// fall through)。這個特殊的注釋并不需要在最後一個語句組中出現。示例：

switch (input) {

case 1:

case 2:

prepareOneOrTwo();

// fall through

case 3:

handleOneTwoOrThree();

break;

default:

handleLargeNumber(input);

}

注意，在case 1後面不需要注釋，隻有在語句組的末尾需要。

4.8.4.3 default的情況要寫出來

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

例外：enum類型的switch語句可以省略default語句組，如果它包括覆寫該類型的所有可能值的顯式情況。這使IDE或其他靜态分析工具能夠在錯過任何情況時發出警告。

4.8.5 注解(Annotations)

注解緊跟在文檔塊後面，應用于類、方法和構造函數，一個注解獨占一行。這些換行不屬于自動換行（章節4.5，自動換行），是以縮進級别不變。示例：

@Override

@Nullable

public String getNameIfPresent() { … }

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

@Override public int hashCode() { … }

應用于字段的注解緊随文檔塊出現，應用于字段的多個注解允許與字段出現在同一行。如：

@Partial @Mock DataLoader loader;

參數和局部變量注解沒有特定規則。

4.8.6 注釋

本節讨論實作注釋。 Javadoc在章節7 Javadoc中單獨講解。

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

4.8.6.1 塊注釋風格

塊注釋與其周圍的代碼在同一縮進級别。它們可以是

// And so

// is this.

注釋不要封閉在由星号或其它字元繪制的架構裡。

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

4.8.7 修飾符

類和成員的修飾符如果存在，則按Java語言規範中推薦的順序出現。

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_，例如testPop_emptyStack。尚未出現給測試方法命名的标準命名準則。

5.2.4 常量名

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

常數是靜态final字段，其内容是不可變的，并且其方法沒有可檢測的函數副作用。這包括基元，字元串，不可變類型和不可變類型的不可變集合。如果任何執行個體的觀測狀态可以改變，它就不是一個常量。靜态final字段不一定都是常量。例如：

// Constants

static final int NUMBER = 5;

static final ImmutableList 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 mutableCollection = new HashSet();

static final ImmutableSet 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風格編寫。

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

5.2.8 類型變量名

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

單個的大寫字母，後面可以跟一個數字（如：E、T、X、T2）。

以類命名方式（章節5.2.2），後面加個大寫的T（如：RequestT、FooBarT）。

5.3 CamelCase：定義

有時不止一種合理的方式可以将短語轉換為CamelCase模式，例如首字母縮略詞或不尋常的結構，如“IPv6”或“iOS”。為了提高可預測性，Google Style指定（盡量）使用以下确定性方案。

從名稱的文本形式開始：

将短語轉換為純ASCII并删除任何省略号。例如：“Müller’s algorithm”可改為“Muellers algorithm”。

以空格和任何剩餘的标點符号（通常為連字元）将結果劃分為單詞。

推薦： 如果有任何詞在常用的情況下已經具有正常的CamelCase外觀，将其拆分為其組成部分（例如，“AdWords”成為“ad words”）。 注意，諸如“iOS”這樣的詞本身不是真正的駱駝情況；它違反任何慣例，是以本建議不适用。

将單詞（包括首字母縮略詞）第一個字元大寫其他字元全小寫：

…将所有字元全大寫

…除第一個字元外，将所有字元全小寫

最後，将所有單詞連接配接成一個詞。

注意，原始單詞樣式幾乎完全被忽略。示例：

文本形式 正确 錯誤

“XML HTTP request” XmlHttpRequest XMLHTTPRequest

“new customer ID” newCustomerId newCustomerID

“inner stopwatch” innerStopwatch innerStopWatch

“supports IPv6 on iOS?” supportsIpv6OnIos supportsIPv6OnIOS

“YouTube importer” YouTubeImporter

YoutubeImporter*

*可接受，但不推薦。

提示： 一些單詞在英語中有不明确的連字元：例如“nonempty”和“non-empty”都是正确的，是以方法名稱checkNonempty和checkNonEmpty也都是正确的。

6 程式設計實踐

6.1 @Override：能用則用

隻要是合法的，就把@Override注解給用上。這包括重寫超類方法的類方法，實作接口方法的類方法，以及重定義超接口方法的接口方法。

例外： 當父方法為@Deprecated時，可以省略@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 靜态成員：使用類進行調用

使用類名調用靜态的類成員，而不是具體某個對象或表達式。

Foo aFoo = …;

Foo.aStaticMethod(); // good

aFoo.aStaticMethod(); // bad

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

6.4 Finalizers: 禁用

極少會去重載Object.finalize。

提示： 不要這麼做，不得已非要這麼做的話，請先仔細閱讀并了解Effective Java Item 7: “Avoid Finalizers”，非常小心，最後還是不要這麼做。

7 Javadoc

7.1 格式

7.1.1 一般形式

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

public int method(String p1) { … }

或者是以下單行形式：

基本形式總是可以接受的。當整個Javadoc塊（包括注釋标記）可以放在單個行上時，可以将其替換為單行形式。注意，這隻适用于沒有塊标簽的情形，如@return。

7.1.2 段落

空行（即僅包含對齊的前導星号（*）的行）出現在段落之間，并在Javadoc标記（如果存在）之前。除了第一個段落，每個段落第一個單詞前都有标簽

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

7.1.3 Javadoc标記

标準的Javadoc标記按以下順序出現：@param、@return、 @throws、@deprecated，且這四種類型不能出項空描述。當描述無法在一行中容納時，連續行需要至少在@縮進的基礎上再縮進至少4個空格。

7.2 摘要片段

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

這隻是一個小片段，可以是一個名詞短語或動詞短語，但不是一個完整的句子。它不會以A {@code Foo} is a…或This method returns…開頭,它也不會是一個完整的祈使句，如Save the record.。然而，由于開頭大寫及被加了标點，它看起來就像是個完整的句子。

提示： 一個常見的錯誤是把簡單的Javadoc寫成 。

7.3 何處需要使用Javadoc

至少在每個public類及它的每個public和protected成員處使用Javadoc，以下是一些例外。

也可能存在其他Javadoc内容，如章節7.3.3所述。

7.3.1 例外：不言自明的方法

對于簡單明顯的方法如getFoo，Javadoc是可選的。這種情況下除了寫"Returns the foo"，确實也沒有什麼值得寫了。

提示： 如果有一些相關資訊是需要讀者了解的，那麼以上的示例不應作為忽視這些資訊的理由。例如，對于名為getCanonicalName的方法，不要省略其文檔（文檔可以僅僅是），可能讀者并不明白“canonical name”具體指什麼

7.3.2 例外：重載

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

7.3.3 非必需Javadoc

對于包外不可見的類和方法，如有需要，也是要使用Javadoc的。

如果一個注釋是用來定義一個類，方法，字段的整體目的或行為，那麼這個注釋應該寫成Javadoc（使用/**）。

不一定要求非必需的Javadoc遵循章節7.1.2、章節7.1.3和章節7.2的格式化規則，當然也是建議遵循的。