Java代碼書寫規範

當不得不違背本規範時，請詳細註釋原因
一、通用規範
1.1命名規範
1. 使用全單詞表示
2. 使用貼切的詞彙
3. 使用大小寫混合
4. 儘量少用縮略詞，否則，維護一個標準的縮略詞表
5. 避免過長，小於15
6. 避免類似的命名或僅在大小寫上區分的命名
7. 標準縮略詞做一個單詞處理
1.2文檔規範
1. 增加註釋，以確保代碼清晰
2. 無需註釋的程序，可能也不值得運行
3. 避免修飾性註釋
4. 保持註釋簡潔
5. 寫代碼之前寫註釋
6. 註釋中說明代碼的原因，而不是結果
二、Java編碼規範
2.1命名和大小寫規範：
下面這些廣泛使用的命名規範可以應用到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
屬性範圍
範圍 描述 用於
public 可以在所有類的方法中引用 最好不定義此類屬性
protected 可以在本類及子類方法中引用 最好不定義此類屬性
private 只能用於同類的方法中 所有屬性都應是此種類型並通過訪問器accessor訪問
6. 參數
方法參數名稱會出現在方法的文檔中，所以參數含義應儘可能明確。一般參數名稱爲一個單詞。
成員函數的參數標準：
使用接口代替類作爲參數，實現多態性
7. 局部變量
命名規則和方法以及屬性的命名規則一樣。
2.2 註釋規範
2.2.1總體說明
1. 三種類型的Java註釋
註釋類型 用於 例子
文檔註釋 寫在類、接口、成員函數和屬性的定義緊前方，由javadoc用於創建類的外部文檔。 /**
* document comments
*/
C風格註釋
暫時註釋不用的代碼 /*
comments
*/
單行註釋
在成員函數中用於註釋商業邏輯，代碼段，變量定義 // comments
文檔註釋的主體部分一開始應該先用一句話概括類、接口、方法或屬性完成的功能，書寫時單獨佔一行。概括性句子的後面還可以跟若干條,詳細介紹類、接口、方法或屬性的註釋語句及段落。
在描述性的段落之後，文檔註釋還可以包括其他一些段落，每個段落都以一個特殊的文檔註釋標籤開始，例如@auther、@param。
2. doc註釋的標籤
@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”>
2.2.2具體註釋內容
1. 註釋類
類功能說明：註釋類的功能
@author 註釋類的作者
@see 註釋引用類的情況
@version 註釋類的版本信息
2. 註釋成員方法
 頭部註釋
1. 功能描述：描述成員方法的功能及存在的原因（必填）
2. @param 參數及名稱描述（必填）
3. @return 返回值（必填）
4. @exception 描述信息
5. @see 引用說明
6. @since 版本號
7. 存在問題：存在的尚未解決的問題
8. 使用範圍：確定使用範圍及原因
9. 外部變動：對其他對象的變動註釋
10. 修改歷史：註明修改時間、修改人、修改內容、修改原因（必填）
11. 調用方法：說明調用的前提條件和事後條件、說明併發調用情況
 內部註釋
1. 在方法內部的開始部分統一註釋方法的邏輯
2. 控制結構，結構性語句的起始位置需要註明，控制結構的尾部
3. 註明局部變量
4. 註釋結束括號}
2.3編寫清晰的代碼
1. 註釋文檔
2. 段落化
3. 多行語句段落化
4. 使用空格和空行
5. 方法不能太長，遵循30秒規則
6. 定義消息的傳遞，在註釋中體現
7. 簡短的命令行
8. 將比較的常數放在左方，以防止誤寫爲賦值語句
三、 JAVA命名縮略詞表
參見縮略詞表。