Java代碼書寫規範

1. 使用全單詞表示

2. 使用貼切的詞彙

3. 使用大小寫混合

4. 盡量少用縮略詞，否則，維護一個标準的縮略詞表

5. 避免過長，小于15

6. 避免類似的命名或僅在大小寫上區分的命名

7. 标準縮略詞做一個單詞處理

1. 增加注釋，以確定代碼清晰

2. 無需注釋的程式，可能也不值得運作

3. 避免修飾性注釋

4. 保持注釋簡潔

5. 寫代碼之前寫注釋

6. 注釋中說明代碼的原因，而不是結果

下面這些廣泛使用的命名規範可以應用到java中的包、類、方法、屬性和常量。因為這些規範的使用非常普遍，而且它們還影響到了我們定義的類的公共api，是以我們應該認真遵守這些規範：

1. 包

   保證包的名稱是唯一的，包的名稱字首以我們的網絡域名稱，包名小寫（例如com.itsv.utils）置于檔案最上一行

2. 類

   第一個字母必須大寫，是以類名稱是大小寫混合的（例如string）；如果類名稱是由多個單詞組成的，那麼每個單詞都應該以大寫字母開頭（例如stringbuffer）；如果一個類名稱或者類名稱中的一個單詞是字母縮寫詞，那麼我們可以把這個縮寫詞中的每個字母都寫成大寫（例如url、htmlparser）。因為設計的類是用來代表對象的，是以我們在為類起名稱時應盡量選擇名詞。

   如果是某一種特殊類别的類，則可以統一采用特殊簡短字尾來辨別，這些字尾全部大寫。例如，對所有處理與資料庫相關的類，可以在類名後加上daoimpl來辨別

引用類： 全部置于包名之後，檔案所定義類名之前

類的定義順序：

class xxx

constructors

finalize

public member functions

protected member functions

private member functions

private fields

3. 接口

   接口名稱遵循的大小寫規則和類名稱是一樣的。用接口來提供一些關于實作它的類的額外資訊，常用形容詞作為接口名稱（例如runnable），當接口更像一個抽象的超類時，我們又用名詞來作為接口的名稱（例如document）

在建立類之前先建立公共接口，以确定類的應用存根，接口的命名用描述性的形容詞或名詞，或者加字首i 或字尾ifc：

runnable

cloneable

singleton

datainput

4. 方法

   方法名稱總是以小寫字母開頭。如果名稱中包含的單詞多于一個（一般使用動詞和名詞組合而成），那麼除第一個單詞外的所有單詞都應該以大寫字母開頭，動詞放在首單詞，例如insert（）、insertobject（）。

成員變量通路方法accessor的命名：

使用getter-get和setter-set方法，對于boolean類型的可以使用is代替get

getter還有can和has

成員方法的範圍：

範圍

描述

正确使用方法

public

任何類或對象的任何成員方法中可以調用

當該方法必須被目前類分支之外的類或對象調用時

protected

隻能被同類及所有子類的成員方法調用

當該方法隻能被目前類及其分支之内的類或對象調用時

private

隻能被同類的成員方法調用，子類的成員方法不能調用

封裝一個類的特有方法，目前類所特有，其他類或子類沒有

預設的為軟體包級可用，對相同軟體包package的類可使用，不能在不同軟體包的類中調用

5. 屬性和常量

   非常量的屬性名稱所遵循的大小寫規則和方法名稱是一樣的。如果一個屬性是靜态final類型的常量，那麼該屬性的所有字母都應該大寫。如果常量的名稱中包含多個單詞，那麼應該用下劃線來分隔這些單詞（例如max_value）。此外，選擇的屬性名稱應該是最能說明屬性或其取值的含義的。

集合屬性(array, vector)采用複數

firstname

orderitems

常量命名

static final max_value

屬性範圍

用于

可以在所有類的方法中引用

最好不定義此類屬性

可以在本類及子類方法中引用

隻能用于同類的方法中

所有屬性都應是此種類型并通過通路器accessor通路

6. 參數

   方法參數名稱會出現在方法的文檔中，是以參數含義應盡可能明确。一般參數名稱為一個單詞。

成員函數的參數标準：

使用接口代替類作為參數，實作多态性

7. 局部變量

   命名規則和方法以及屬性的命名規則一樣。

注釋類型

例子

文檔注釋

寫在類、接口、成員函數和屬性的定義緊前方，由javadoc用于建立類的外部文檔。

/**

 * document comments

 */

c風格注釋

暫時注釋不用的代碼

/*

   comments

單行注釋

在成員函數中用于注釋商業邏輯，代碼段，變量定義

// comments

文檔注釋的主體部分一開始應該先用一句話概括類、接口、方法或屬性完成的功能，書寫時單獨占一行。概括性句子的後面還可以跟若幹條,詳細介紹類、接口、方法或屬性的注釋語句及段落。

在描述性的段落之後，文檔注釋還可以包括其他一些段落，每個段落都以一個特殊的文檔注釋标簽開始，例如@auther、@param。

@author 名稱   後加上相應的作者

@version 文本  插入指定文本的版本資訊

@param 參數-名稱描述

@return 描述

@exception 完整的類名稱 描述資訊

@throws 完整的類名稱 描述資訊

@see 引用其他類，格式如下：@see 類名  

                           @see 完整類名

                           @see 完整類名#方法名

{@link引用}

@deprecated 解釋

@since 版本号

@serial 描述資訊

@serialfield名稱 類型 描述資訊

@serialdata描述資訊

@beaninfo資訊

文檔注釋的描述資訊可以包括簡單的html标注标簽，不包括html的主要結構标簽，例如<h2>和<hr>等。

在文檔注釋中使用标簽{@link}來引用超級連結或者是交叉引用，避免用标簽<a>。

如果希望在文檔注釋中包括圖像，可以把圖像檔案放在源代碼目錄下的doc檔案的子目錄中，然後把圖像取名為和類一樣的名稱，并在名稱之後加上數字作為字尾，例如，可以在叫做circle類的文檔注釋中包括下面這個html标簽，它定義了出現在注釋中的第二張圖檔：<img src=”doc-files/circles-2.gif”> 

類功能說明：注釋類的功能

@author 注釋類的作者

@see  注釋引用類的情況

@version 注釋類的版本資訊

l 頭部注釋

1. 功能描述：描述成員方法的功能及存在的原因（必填）

2. @param 參數及名稱描述（必填）

3. @return 傳回值（必填）

4. @exception 描述資訊

5. @see 引用說明

6. @since 版本号

7. 存在問題：存在的尚未解決的問題

8. 使用範圍：确定使用範圍及原因

9. 外部變動：對其他對象的變動注釋

10. 修改曆史：注明修改時間、修改人、修改内容、修改原因（必填）

11. 調用方法：說明調用的前提條件和事後條件、說明并發調用情況

l 内部注釋

1. 在方法内部的開始部分統一注釋方法的邏輯

2. 控制結構，結構性語句的起始位置需要注明，控制結構的尾部

3. 注明局部變量

4. 注釋結束括号}

1. 注釋文檔

2. 段落化

3. 多行語句段落化

4. 使用空格和空行

5. 方法不能太長，遵循30秒規則

6. 定義消息的傳遞，在注釋中展現

7. 簡短的指令行

8. 将比較的常數放在左方，以防止誤寫為指派語句

參見縮略詞表。