Android編碼規范

源文件基礎

文件名

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

文件編碼：UTF-8

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

特殊字符

空白字符

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

所有其它字符串中的空白字符都要進行轉義。
制表符不用于縮進（可以在IDE中Tab鍵設置為若干個空格）。

特殊轉義序列

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

非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 | Good，對于非打印字符，使用轉義，并在必要時寫上注釋

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

源文件結構

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

許可證或版權信息(如有需要)
package語句
import語句
一個頂級類(只有一個)以上每個部分之間用一個空行隔開。

許可證或版權信息

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

package語句

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

import語句

import不要使用通配符

即，不要出現類似這樣的import語句：import java.util.*;

不要換行

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

間距

import語句分組，每組由一個空行分隔：

類聲明

只有一個頂級

類聲明每個頂級類都在一個與它同名的源文件中(當然，還包含.java后綴)。
例外：package-info.java，該文件中可沒有package-info類。

類成員順序

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

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

區塊劃分

建議使用注釋將源文件分為明顯的區塊，區塊劃分如下

常量聲明區
UI控件成員變量聲明區
普通成員變量聲明區
內部接口聲明區
初始化相關方法區
事件響應方法區
普通邏輯方法區
重載的邏輯方法區
發起異步任務方法區
異步任務回調方法區
生命周期回調方法區（出去onCreate()方法）
內部類聲明區

類成員排列通用規則

按照發生的先后順序排列
常量按照使用先后排列
UI控件成員變量按照layout文件中的先后順序排列
普通成員變量按照使用的先后順序排列
方法基本上都按照調用的先后順序在各自區塊中排列
相關功能作為小區塊放在一起（或者封裝掉）

重載：永不分離

當一個類有多個構造函數，或是多個同名方法，這些函數/方法應該按順序出現在一起，中間不要放進其它函數/方法。

塊狀結構

塊狀結構(block-like construct)指的是一個類，方法或構造函數的主體。需要注意的是，數組初始化中的初始值可被選擇性地視為塊狀結構。

大括號

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

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

非空塊：K & R 風格

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

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

示例：

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

空塊：可以用簡潔版本

一個空的塊狀結構里什么也不包含，大括號可以簡潔地寫成{}，不需要換行。

例外：如果它是一個多塊語句的一部分(if/else 或 try/catch/finally) ，即使大括號內沒內容，右大括號也要換行。
示例：
void doNothing() {}

塊縮進：4個空格

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

換行，空行

一個語句一行，每個語句后要換行。
每個代碼塊之間空一行。

空格

1. 運算符的兩邊要空一格
2. 左大括號之前空一格c
3. 右大括號之后有語句的話空一格
4. if之后空一格，else前后都空一格
5. catch， finally前后都空一格
6. 逗號后面空一格
7. 單詞之間空一格，不要多
8. 類型強轉前后各空一格
9. 控制語句的條件的括號前后空一格（if、switch、while...）
10. 以上規則重疊只空一格

列限制：80或100

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

例外：

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

自動換行

術語說明：一般情況下，一行長代碼為了避免超出列限制(80或100個字符)而被分為多行，我們稱之為自動換行(line-wrapping)。我們并沒有全面，確定性的準則來決定在每一種情況下如何自動換行。很多時候，對于同一段代碼會有好幾種有效的自動換行方式。

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

從哪里斷開

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

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

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

自動換行時，第一行后的每一行至少比第一行多縮進8個空格(注意：制表符不用于縮進。見2.3.1節)。當存在連續自動換行時，縮進可能會多縮進不只8個空格(語法元素存在多級時)。一般而言，兩個連續行使用相同的縮進當且僅當它們開始于同級語法元素。
不鼓勵使用可變數目的空格來對齊前面行的符號。

空白

垂直空白

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

1. 類內連續的成員之間：字段，構造函數，方法，嵌套類，靜態初始化塊，實例初始化塊。 例外： 兩個連續字段之間的空行是可選的，用于字段的空行主要用來對字段進行邏輯分組。
2. 在函數體內，語句的邏輯分組間使用空行。
3. 類內的第一個成員前或最后一個成員后的空行是可選的(既不鼓勵也不反對這樣做，視個人喜好而定)。
4. 要滿足本文檔中其他節的空行要求(比如3.3節：import語句)
5. 多個連續的空行是允許的，但沒有必要這樣做(我們也不鼓勵這樣做)。

水平空白

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

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

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

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

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

4. 在任何二元或三元運算符的兩側。這也適用于以下”類運算符”符號：

   • 類型界限中的&()。
   • catch塊中的管道符號(catch (FooException | BarException e)。
   • foreach語句中的分號。

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

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

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

8. 數組初始化中，大括號內的空格是可選的，即new int[] {5, 6}和new int[] { 5, 6 }都是可以的。
   注意：這個規則并不要求或禁止一行的開關或結尾需要額外的空格，只對內部空格做要求。

水平對齊(可選)

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

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

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的工作并且可能導致更多的合并沖突。

用小括號來限定組：推薦

除非作者和reviewer都認為去掉小括號也不會使代碼被誤解，或是去掉小括號能讓代碼更易于閱讀，否則我們不應該去掉小括號。

我們沒有理由假設讀者能記住整個Java運算符優先級表。

具體結構

枚舉類

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

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

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

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

變量聲明

每次只聲明一個變量

不要使用組合聲明，比如int a, b;。

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

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

數組

數組初始化：可寫成塊狀結構

數組初始化可以寫成塊狀結構，比如，下面的寫法都是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}

非C風格的數組聲明

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

switch語句

術語說明：switch塊的大括號內是一個或多個語句組。
每個語句組包含一個或多個switch標簽(case FOO:或default:)，后面跟著一條或多條語句。

縮進

與其它塊狀結構一致，switch塊中的內容縮進為2個空格。每個switch標簽后新起一行，再縮進2個空格，寫下一條或多條語句。

Fall-through：注釋

在一個switch塊內，每個語句組要么通過break, continue, return或拋出異常來終止，要么通過一條注釋來說明程序將繼續執行到下一個語句組， 任何能表達這個意思的注釋都是OK的(典型的是用// fall through)。這個特殊的注釋并不需要在最后一個語句組(一般是default)中出現。

示例：

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

default的情況要寫出來

每個switch語句都包含一個default語句組，即使它什么代碼也不包含。

注解(Annotations)

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

例如：

@Nullable public String getNameIfPresent() { … }

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

例如：

@Override public int hashCode() { … }應用于字段的注解緊隨文檔塊出現，應用于字段的多個注解允許與字段出現在同一行。

例如：

@Partial @Mock DataLoader loader;

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

注釋

塊注釋風格

塊注釋與其周圍的代碼在同一縮進級別。它們可以是/ … /風格，也可以是// …風格。對于多行的/ … /注釋，后續行必須從開始， 并且與前一行的對齊。

以下示例注釋都是OK的。

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

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

注意：在寫多行注釋時，如果你希望在必要時能重新換行(即注釋像段落風格一樣)，那么使用/ … /。

Modifiers

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

public protected private abstract static final transient Volatile synchronized native strictfp

常見命名法

1. 小駝峰式命名法（lower camel case）：
   第一個單字以小寫字母開始，第二個單字的首字母大寫。例如：firstName、lastName。
2. 大駝峰式命名法（upper camel case）：
   每一個單字的首字母都采用大寫字母，例如：FirstName、LastName、CamelCase，也被稱為 Pascal（帕斯卡） 命名法。
3. 匈牙利命名法：
   通過在變量名之前增加小寫字母的符號前綴，以標識變量的屬性、類型、作用域等參數。簡單地說，即“變量名＝屬性＋類型＋對象描述”的形式。
4. 下劃線命名法：
   單詞與單詞間用下劃線做間隔。例如：tv_title

標識符類型的規則

對所有標識符都通用的規則

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

包名

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

采用反域名命名規則，全部使用小寫字母。一級包名為com，二級包名為xx（可以是公司或則個人的隨便），三級包名根據應用進行命名，四級包名為模塊名或層級名。

注意：
如果項目采用MVP，所有M、V、P抽取出來的接口都放置在相應模塊的i包下，所有的實現都放置在相應模塊的impl下

類名

類名都以大駝峰命名法（UpperCamelCase）風格編寫。

類名通常是名詞或名詞短語，接口名稱有時可能是形容詞或形容詞短語。現在還沒有特定的規則或行之有效的約定來命名注解類型。

名詞，采用大駝峰命名法，盡量避免縮寫，除非該縮寫是眾所周知的， 比如HTML,URL，如果類名稱中包含單詞縮寫，則單詞縮寫的每個字母均應大寫。

測試類的命名以它要測試的類的名稱開始，以Test結束。
例如：HashTest 或 HashIntegrationTest。

接口（interface）：命名規則與類一樣采用大駝峰命名法，多以able或ible結尾，如
interface Runnable ;
interface Accessible。

注意：
如果項目采用MVP，所有Model、View、Presenter的接口都以I為前綴，不加后綴，其他的接口采用上述命名規則。

方法名

方法名都以小駝峰命名法 (LowerCamelCase) 風格編寫。

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

下劃線可能出現在JUnit測試方法名稱中用以分隔名稱的邏輯組件。一個典型的模式是：test_，例如：testPop_emptyStack。

并不存在唯一正確的方式來命名測試方法。

常量名

常量名都以下劃線命名法風格編寫。模式為CONSTANT_CASE，全部字母大寫，用下劃線分隔單詞。

每個常量都是一個靜態final字段，但不是所有靜態final字段都是常量。在決定一個字段是否是一個常量時，考慮它是否真的感覺像是一個常量。

例如，如果任何一個該實例的觀測狀態是可變的，則它幾乎肯定不會是一個常量。只是永遠不打算改變對象一般是不夠的，它要真的一直不變才能將它示為常量。

非常量字段名

非常量字段名以小駝峰命名法 (LowerCamelCase) 風格的基礎上改造為如下風格：

基本結構為scopeVariableNameType，

scope：范圍

非公有，非靜態字段命名以m開頭。

靜態字段命名以s開頭。

公有非靜態字段命名以p開頭。

公有靜態字段（全局變量）命名以g開頭。

public static final 字段(常量) 全部大寫，并用下劃線連起來。

例子：

public class MyClass {  
       public static final int SOME_CONSTANT = 42;  
       public int pField;  
       private static MyClass sSingleton;  
       int mPackagePrivate;  
       private int mPrivate;  
       protected int mProtected; 
       public static int gField; 
}

使用1字符前綴來表示作用范圍，1個字符的前綴必須小寫，前綴后面是由表意性強的一個單詞或多個單詞組成的名字，而且每個單詞的首寫字母大寫，其它字母小寫，這樣保證了對變量名能夠進行正確的斷句。

Type：類型

考慮到Android中使用很多UI控件，為避免控件和普通成員變量混淆以及更好達意，所有用來表示控件的成員變量統一加上控件縮寫作為后綴（文末附有縮寫表）。

對于普通變量一般不添加類型后綴，如果統一添加類型后綴，請參考文末的縮寫表。

用統一的量詞通過在結尾處放置一個量詞，就可創建更加統一的變量，它們更容易理解，也更容易搜索。

注意：如果項目中使用ButterKnife，則不添加m前綴，以LowerCamelCase風格命名。

例如，請使用 mCustomerStrFirst 和 mCustomerStrLast，而不要使用mFirstCustomerStr和mLastCustomerStr。

量詞列表：量詞后綴說明

First 一組變量中的第一個
Last 一組變量中的最后一個
Next 一組變量中的下一個變量
Prev 一組變量中的上一個
Cur 一組變量中的當前變量。

說明：

集合添加如下后綴：List、Map、Set

數組添加如下后綴：Arr

注意：所有的VO（值對象）統一采用標準的lowerCamelCase風格編寫，所有的DTO（數據傳輸對象）就按照接口文檔中定義的字段名編寫。

參數名

參數名以LowerCamelCase風格編寫

局部變量名

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

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

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

臨時變量

臨時變量通常被取名為i，j，k，m和n，它們一般用于整型；c，d，e，它們一般用于字符型。 如： for (int i = 0; i < len ; i++)，并且它和第一個單詞間沒有空格。

類型變量名

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

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

資源文件命名規范

布局文件(XML文件(layout布局文件))：

全部小寫，采用下劃線命名法：

1. contentview 命名
   必須以全部單詞小寫，單詞間以下劃線分割，使用名詞或名詞詞組。
   所有Activity或Fragment的contentView必須與其類名對應，對應規則為：
   將所有字母都轉為小寫，將類型和功能調換（也就是后綴變前綴）。
   例如：activity_main.xml

2. Dialog命名：dialog_描述.xml
   例如：dialog_hint.xml

3. PopupWindow命名：ppw_描述.xml
   例如：ppw_info.xml

4. 列表項命名：item_描述.xml
   例如：item_city.xml

5. 包含項命名：模塊_(位置)描述.xml
   例如：activity_main_head.xml、activity_main_bottom.xml
   注意：通用的包含項命名采用：項目名稱縮寫_描述.xml
   例如：xxxx_title.xml

圖片文件(圖片mipmap/drawable文件夾下)：

全部小寫，采用下劃線命名法，加前綴區分
命名模式：可加后綴 _small 表示小圖, _big 表示大圖，邏輯名稱可由多個單詞加下劃線組成，采用以下規則：
用途_模塊名_邏輯名稱
用途_模塊名_顏色
用途_邏輯名稱
用途_顏色
說明：用途也指控件類型（具體見UI控件縮寫表）

例如：
btn_main_home.png 按鍵
divider_maket_white.png 分割線
ic_edit.png 圖標
bg_main.png 背景
btn_red.png 紅色按鍵
btn_red_big.png 紅色大按鍵
ic_head_small.png 小頭像
bg_input.png 輸入框背景
divider_white.png 白色分割線
如果有多種形態如按鈕等除外如 btn_xx.xml（selector）

注意：
使用AndroidStudio的插件SelectorChapek可以快速生成selector，前提是命名要規范。

動畫文件（anim文件夾下）：

全部小寫，采用下劃線命名法，加前綴區分。
具體動畫采用以下規則：
模塊名_邏輯名稱

邏輯名稱：
refresh_progress.xml
market_cart_add.xml
market_cart_remove.xml
普通的tween動畫采用如下表格中的命名方式
// 前面為動畫的類型，后面為方向

values中name命名

layout中的id命名

命名模式為：view縮寫_view的邏輯名稱
在Activity中的變量命名使用 view 縮寫做后綴，如：mUserNameTV（展示用戶名的TextView）

編程實踐

@Override：能用則用

只要是合法的，就把@Override注解給用上。

捕獲的異常：不能忽視

除了下面的例子，對捕獲的異常不做響應是極少正確的。(典型的響應方式是打印日志，或者如果它被認為是不可能的，則把它當作一個 AssertionError 重新拋出。)

如果它確實是不需要在catch塊中做任何響應，需要做注釋加以說明(如下面的例子)。

try {
    int i = Integer.parseInt(response);
    return handleNumericResponse();
} catch (NumberFormatException ok) {
    // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

例外：在測試中，如果一個捕獲的異常被命名為expected，則它可以被不加注釋地忽略。下面是一種非常常見的情形，用以確保所測試的方法會拋出一個期望中的異常，因此在這里就沒有必要加注釋。

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

捕獲具體的異常，不要直接捕獲Exception

try {
    emptyStack.pop();
    fail();
} catch (NoSuchElementException expected) { //good
//} catch (Exception expected) { //bad
}

靜態成員：使用類進行調用

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

Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad

Javadoc

格式

一般形式

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

/**
* Multiple lines of Javadoc text are written here,
* wrapped normally...
* @param str String Value
* @return A Int Value
* @throws   ... 
* @deprecated   ...
* @see ...
* {@link包.類#成員 標簽}
*/
 public int method(String str) { ... }

或者是以下單行形式：

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

基本格式總是OK的。當整個Javadoc塊能容納于一行時(且沒有Javadoc標記@XXX)，可以使用單行形式。

段落

空行(即，只包含最左側星號的行)會出現在段落之間和Javadoc標記(@XXX)之前(如果有的話)。

除了第一個段落，每個段落第一個單詞前都有標簽，并且它和第一個單詞間沒有空格。

Javadoc標記

標準的Javadoc標記按以下順序出現：@param, @return, @throws, @deprecated,

前面這4種標記如果出現，描述都不能為空。 當描述無法在一行中容納，連續行需要至少再縮進4個空格。

摘要片段

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

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

注意：
一個常見的錯誤是把簡單的Javadoc寫成
/** @return the customer ID */，這是不正確的。它應該寫成/** Returns the customer ID. */。

哪里需要使用Javadoc

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

例外：不言自明的方法

對于簡單明顯的方法如getFoo，Javadoc是可選的(即，是可以不寫的)。這種情況下除了寫”Returns the foo”，確實也沒有什么值得寫了。

單元測試類中的測試方法可能是不言自明的最常見例子了，我們通常可以從這些方法的描述性命名中知道它是干什么的，因此不需要額外的文檔說明。

注意：
如果有一些相關信息是需要讀者了解的，那么以上的例外不應作為忽視這些信息的理由。例如，對于方法名getCanonicalName，

就不應該忽視文檔說明，因為讀者很可能不知道詞語canonical name指的是什么。

例外：重載

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

可選的Javadoc

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

UI控件縮寫表

常見的英文單詞縮寫

程序中使用單詞縮寫原則：不要用縮寫，除非該縮寫是約定俗成的。