Java 編碼規範

• Top
• 0. 規範的規範
• 1. 代碼格式
• 2. 命名
• 2.1 包
• 2.2 類和介面
• 2.3 成員變數
• 2.4 常量
• 2.5 局部變數
• 2.6 成員函數和靜態函數
• 3. 注釋
• 3.1 類 Java Doc
• 3.2 函數 Java Doc
• 3.3 欄位 Java Doc
• 3.4 函數內部注釋
• 4. 編程
• 5. 單元測試

 

 

#Top

 

0. 規範的規範

1. 本規範的每一條目必須無二義性，並且可執行。否則作廢
2. 本規範的條目分為兩個層級:

• 規則 -R
• 建議 -S

本規範所有的“規則”條目必須被遵守

 

#Top

 

1. 代碼格式

1. R -使用統一的 Eclipse 的代碼格式:http://code.google.com/p/nutz/source/browse/trunk/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml

• 請從 svn 的 trunk/doc/eclipse/nutz-eclipse-java-code-format-1.0.xml 獲得此檔案

S -非 Eclipse 使用者請閱讀上述 XML 代碼自行遵守

• 基本上我們沒有為非 Eclipse 使用者指定規範，我們還沒有一個好辦法

 

#Top

 

2. 命名

 

#Top

 

2.1 包

1. R -包名必須全部小寫，2個以內單詞。
1. S -最好為 1 個單數名詞
2. R -所有項目的包要以 “org.nutz” 為父 包 。

 

#Top

 

2.2 類和介面

1. S -最好為名詞
2. R -命名類和介面時，需要將所有單詞的首字母大寫。
3. R -介面的命名不採用首字母為 I 或加上 IF 尾碼的命名方式 。例 如 ：IBookDao 、 BookDaoIF 等 。
4. R -抽象類別必須使用 Abstract 作為類名的首碼，而介面建議使用 Interface 作為 介面名尾碼。
5. R -異常類應該使用 Exception 做為 名稱 尾碼。
6. R -如果是運行一次就拋棄的類，以 ing 結尾，比如Rendering
7. R -類名盡量短，但是最好不要縮寫，如果縮寫，必須為特別常用的類，比如 org.nutz.dao.Cnd

• 因為調用者書寫你的類名太長，他(她)的IDE會自動替他(她)換行，他會覺得有點不爽

R -不要和 Java 的標準庫中的類名衝突，比如 Class, Object, String 等

• 如果衝突，就表示你極其藐視 Java 標準庫中的那個的設計
• 調用者需要花更多的時間和代碼來明確他使用的是你的類, 而不是標準庫中的那個

S -以下情況可以允許寫奇怪類名 --名稱簡短，讓人一眼不知道什麼意思，用了以後一眼就能知道什麼意思

• 類特別常用
• 類非常特殊，難以歸類
• 私人類或內部類
• 不推薦其他人調用的 公有、保護、預設類
• 起個奇怪的名字，就是不想讓你關心這個類的代碼

R -預設介面實現應該使用 Default 名稱 首碼 。例 如 ： DefaultEntityMaker。

• 也可以採用 Impl 作為尾碼，表示這個實現為此介面的最優實現或者唯一實現

 

#Top

 

2.3 成員變數

1. S -最好為單數名詞
2. R -能 private 就不要 default，能 default 就不要 protected，最好不要 public
3. R -如果是集合或數組，用複數名詞

• Map pets， 比 Map petMap 要好

R -不要用一個字母，尤其是 i，你可以用 index 或者 cursor 來代替

 

#Top

 

2.4 常量

1. R -命名常量（帶有 final 修飾符的域）時需分隔。如 ： public final int MAX_VALUE = 30 。

 

#Top

 

2.5 局部變數

1. R -局域變數名要盡量短，推薦用縮寫，比如 StringBuilder sb
2. R -總的來說局部變數請隨意命名，越短越好

比如這個就不好

 publicString abc(String str){
        AbcObjectSet abcObjectSet =newAbcObjectSet();
        abcObjectSet.setName(str);
        return abcObjectSet.getBrief();
 }

而這個就很容易閱讀了：

 publicString abc(String str){
        AbcObjectSet aos =newAbcObjectSet();
        aos.setName(str);
        return aos.getBrief();
 }

 

#Top

 

2.6 成員函數和靜態函數

1. R -除了 setter / getter，其他的函數採用動詞或者動名短語
2. S -以下情況可以允許寫奇怪函數 --名稱簡短，讓人一眼不知道什麼意思，用了以後一眼就能知道什麼意思
1. 函數特別常用
2. 函數非常特殊
3. 私人函數或預設函數
3. S -支援鏈式賦值的 setter 允許寫成 ，並且也可以支援同名 getter

// Setter
publicPet name(String name){
        this.name = name;
        returnthis;
}

// Getter
publicString name(){
        returnthis.name;
}

 

#Top

 

3. 注釋

1. R -注釋必須和代碼保持同步 。
2. R -注釋中的第一個句子要以（英文）句號、問號或者驚嘆號結束。 Java成工具會將注釋中的第一個句子放在方法匯總表和索引中。
3. R -如果注釋中有超過一個段落，用 <P> 標籤 分隔。
4. R -如果注釋中有多個章節，用 <H2> 標籤聲明每個章節的標題。
5. R -如果注釋需要換行，用 <BR> 標籤。
6. R -範例程式碼以 <PRE></PRE> 包裹。

 

#Top

 

3.1 類 Java Doc

1. R -要著名作者，格式為 @Author XiaoMing(xm@gmail.com)
2. R -繼承的方法可以省略注釋，但是被繼承方法必須有注釋。

 

#Top

 

3.2 函數 Java Doc

1. R -簡單的 get/set 方法可以省略注釋。
2. R -繼承的方法可以省略注釋，但是被繼承方法必須有注釋。

 

#Top

 

3.3 欄位 Java Doc

• R -沒有更多說明了

 

#Top

 

3.4 函數內部注釋

• R -行注釋和塊注釋都是可以被接受的
• R -不要寫 JAVA DOC，沒意義
• R -代碼品質不好但能正常運行，或者還沒有實現的代碼用 “ //TODO: ”
• R -在 if ... else .. 分支上做注釋格式應該如下：

// comments for case A
if(xxxx){
        //TODO you code here
}
/*
 * Multipline comments for case B
 */
elseif(xxxxx){
        //TODO you code here
}
// comments for default case
else{
        //TODO you code here
}

 

#Top

 

4. 編程

1. R -你的每一次提交，必須都是編譯通過的
2. R -你的每一次提交，最好都是通過 JUnit 測試的

• 除非有特別的情況 -- 比如你要和其他人分享的修改

R -無論任何時候，同樣的功能，一段更短的代碼，總比更長的代碼要好

• 這裡的“短”，主要指的是“邏輯”短，而不是“字元長度”短

R -刪掉一段代碼的貢獻，比增加一段代碼的貢獻要大，至少不比它小

R -避免過度設計

• 先讓代碼能工作，然後重構成為優美的代碼
• 你需要知道，“介面”固定了架構，“類” 不是，當它進化為介面的時候就固定了
• 代碼結構設計請遵循《草坪原則 》

 

#Top

 

5. 單元測試

1. R -用例名請用 "長名 " - 一句話，用底線_代替空白

• 通過這個名字，基本可以瞭解測試是幹什麼的

R -主要介面和實作類別要儘可能多的被用例覆蓋