標籤：java 編程規範
一. 編寫背景本文檔的編寫從簡，絕大多數內容以條款或者表格形式列出，不做過多的補充說明,代碼格式規範遵循eclipse的預設編碼規範要求.
二. 適用範圍後台開發人員
總則規範制定總則? 簡單，易執行
命名總體原則1. 名字含義要明確，做到見名知義,如: User,Role, UserManager
2. 盡量使用英文名字作為變數名，如果要使用中文，請寫上備忘.
如：var hbType = null;// hb是中文“貨幣”的首字母縮寫.
3. 採用大小寫混合形式命名，提高名字的可讀性
正確：UserManager
錯誤: usermanager
4. 盡量少用縮寫，但如果一定要使用，就要謹慎地使用。
應該保留一個標準縮寫的列表，並且在使用時保持一致。例如，想對單詞“number”採用縮寫，使用 num 這種格式，並且只使用這一種形式.注意：要維護縮寫詞彙列表.
5. 所有檔案的名稱都是大寫字母開頭，大小寫混合, 如UserList.jsp
6. 所有目錄的名稱都是小寫字母開頭，大小寫混合, 如userType
7. 變數名不能以底線開頭，如“_account”,”_userName”是不允許的，因為底線開頭的變數可能被OWK平台做為保留字佔用.
8. 避免使用相似或者僅在大小寫上有區別的名字
例如，不應同時使用變數名 persistentObject 和 persistentObjects，以及 anSqlDatabase 和 anSQLDatabase。
代碼注釋原則1. 注釋應該簡單清晰，避免使用裝飾性內容，也就是說，不要使用象廣告橫幅那樣的備註陳述式。
2. 代碼注釋的目的是要使代碼更易於被同時參與程式設計的開發人員以及其他後繼開發人員理解。
3. 先寫注釋，後寫代碼。
寫代碼注釋的最好方法是在寫代碼之前就寫注釋。這使你在寫代碼之前可以想想代碼的功能和運行。而且這樣確保不會遺漏注釋。(如果程式的邏輯稍微複雜點的話，這樣做非常有效)
4. 注釋資訊不僅要包括代碼的功能，還應給出原因。
例如，下面例 1 中的代碼顯示金額在 $1,000 以上（包括 $1,000）的定單可給予 5% 的折扣。為什麼要這樣做呢？難道有一個商業法則規定大額定單可以得到折扣嗎？這種給大額定單的特殊是有時限的呢，還是一直都這樣？最初的程式設計者是否只是由於慷慨大度才這樣做呢？除非它們在某個地方（或者是在原始碼本身，或者是在一個外部文檔裡）被注釋出來，否則你不可能知道這些。
if (grandTotal >= 1000.00)
{
grandTotal = grandTotal * 0.95;
}
三 規範內容命名包包結構定義=${包單元}[.${包單元}]*
說明：
1:一個包是由一個或多個構造單元組成,各構造單元之間以點號”.”隔開
2:一個包單元由一個或多個片語成
3:包單元應該是名詞
? 業務系統的包結構是com.cmb.zct.${業務系統名字}.${模組名}
? 包名全部小寫，如：com.cmb.zct.tx.OA.common是不允許的.但有種情況下允許出現大寫字母,就是當包單元是由多個片語成時.如： com.cmb.zct.tx.oa.userType.
類? 使用完全的英文描述符，所有單詞的第一個字母要大寫，並且單詞中大小寫混合。
? 類名是名詞或名詞片語.如 LogManager
? 工具類以Util結尾 . 如FileUtil,StrUtil
? 異常類以Exception結尾.如RootDirNotExistsException
? 抽象類別名以Abstract開頭 AbstractGenerator
? 工廠類以Factory結尾,如 ConnFactory
? 介面同類名，大小寫混合..
方法? 成員函數的命名應採用完整的英文描述符，大小寫混合使用：所有中間單詞的第一個字母大寫。成員函數名稱的第一個單詞常常採用一個有強烈動作色彩的動詞。首個單詞小寫。如：getUserInfo, removeEquipment
參數變數 以 小寫p開頭
如
public void sendMessage(String pMessage){
...............
}
注意：javabean 的參數變數不帶p。
常量名採用完整的英文大寫單詞，在詞與詞之間用底線串連。
MAX_VALUE，DEFAULT_START_DATE
目錄名 同包名，小寫字母開頭，如果有多個單詞構成，則第2個以後的單詞以大寫字母開頭。如user, userType目錄
檔案名稱 同類名命名規則，大寫字母開頭，大小寫混合。如：EquipmentList.jsp
模組相關檔案命名約束，為了方便說明，${MODEL_NAME}代表實際模組的名稱,那各檔案的名字必須滿足下表格式要求.
檔案 格式 舉例
業務組件介面 I${MODEL_NAME}Facade.java IUserFacade.java
服務元件介面 I${MODEL_NAME}Service.java IUserService.java
業務組件實作類別 ${MODEL_NAME}FacadeImpl.java UserFacadeImpl.java
服務元件實作類別 ${MODEL_NAME}ServiceImpl.java IUserServiceImpl.java
測試類別 ${MODEL_NAME}ServiceTest.java UserServiceTest.java
模組設定檔 Spring設定檔 ${MODEL_NAME}.spring.xml User.spring.xml
Sqlmap配置 ${MODEL_NAME}.sqlmap.xml User.sqlmap.xml
種子檔案 ${MODEL_NAME}Service.seed.xml UserService.seed.xml
JAVA源檔案結構
/*
*Copyright (c) 2007-2008
*/
package com.owk.sgtz.util;
import java.io.Serializable;
import java.util.List;
/**
*
* @author HO074337
*
*/
public class Test extends Object implements Serializable{
/* 變數注釋 */
public static final int PKG_HEADER_MAX_LEN = 20;
/* */
protected static int i = 0;
int j = 0;
private int k;
/**
*方法注釋
* @param i
*/
public Test(int i){
}
/***
* 方法注釋
*
*/
public void printInfo(){
}
}
說明：
? 首行是著作權資訊
? 空一行，定義包名
? 空一行，聲明要import的類
? 空一行，編寫類的注釋
? 緊挨著，定義類
? 空一行，定義變數
? 空一行，定義建構函式
? 空一行，定義方法
注釋概念
Java程式有兩類注釋：
實現注釋(implementation comments)和文檔注釋(document comments)。實現注釋是那些在C++中見過的，使用/*...*/和//界定的注釋。
文檔注釋(被稱為"doc comments")是Java專屬的，並由/**...*/界定。文檔注釋可以通過javadoc工具轉換成HTML檔案.本規範只對文檔注釋進行約束，程式注釋由開發人員自行把握,但應該遵循代碼注釋原則
類的注釋/**
*
* @author HO074337
* @version 1.0
* 建立日期：20071010
*
* 功能描述：
* 類的功能描述，闡述這個類的主要功能
*
* 已知的問題:
* 如果一個類有任何突出的問題，應說明出來，讓其他的開發人員瞭解這個類的缺點/痛點。
* 此外，還應註明為什麼不解決問題的原因
*
* 維護曆史:
* 列出日期、類的作者和修改概要。這樣做的目的是讓進行維護的程式員瞭解過去曾對一個
* 類所做的修改，是誰做了什麼樣的修改
* 如：
* huangyh 20071010
* 增加了getUserById(String)方法,使用該方法可以擷取使用者物件
*
* zhangw 20071008
* 將private方法 removeUser() 設定為public,因為在 XX模組需要使用.
*
*/
變數注釋 /**
* 通訊前序的最大長度
*/
public static final int PKG_HEADER_MAX_LEN = 20;
注意：所有public ,protected或預設的變數，都必須採用文檔注釋符號，因為這些注釋資訊需要
匯出到文檔。
Private變數，可以用單行注釋，多行注釋，或者文檔注釋，不做限制
變數描述要說明變數的用途.如果是枚舉性質的變數，請注釋清楚有效值範圍.
方法注釋 /**
* 功能描述：
* 方法提供什麼功能.
*
* 已知問題:
* 如果方法的實現存在某些問題時，需要在這進行說明，以便後續維護人員
* 把問題解決，或者規避.
*
* 使用樣本:
* 簡單的函數調用樣本
*
* @param pMsg 參數名稱 參數描述
* @return 傳回值說明
* @exception 異常說明
*/
任務標註在注釋中使用TODO來標識某些未實現(bogus)的但可以工作(works)的內容。用FIXME來標識某些假的和錯誤的內容。
如: /**
* TODO: XXX有效性檢驗.
*/
/**
* FIXME: 這段代碼存在嚴重的效能問題，系統正式發布前一定要修複
*/
這些標住資訊在eclipse的Tasks視圖中可以看
異常
1. 所有業務異常（帳號不存在，密碼錯誤等）都必須直接或者間接從com.cmb.zct.common.exception. BusinessException派生
2. 所有系統異常（主鍵衝突，SQL語句本身句法錯誤）都必須直接或者間接從com.cmb.zct.common.exception.SysException 派生
日誌1. 不準使用System.out.println/System.err.println 輸出調試資訊
2. 統一使用common log 輸出日誌
3. 日誌對象的定義
private final Log log = LogFactory.getLog( BaseJDBCDAO.class );
或者
private final static Log log = LogFactory.getLog( BaseJDBCDAO.class );
編碼方式所以牽涉到編碼方式的地方，全部統一使用utf-8編碼
編程慣例
1. 類成員變數不設定為public 的，除非是static final 常量
2. 該用類名訪問靜態方法而不是對象. 如: StringUtil.trim
3. 將工具類的建構函式設定為private,避免client端構造對象來調用工具方法
4. 位於for迴圈中作為計數器值的數字常量，除了-1,0和1之外，不應被直接寫入代碼.應該先定義常量變數
5. 一般而言，在含有多種運算子的運算式中使用圓括弧來避免運算子優先順序問題，是個好方法。即使運算子的優先順序對你而言可能很清楚，但對其他人未必如此。你不能假設別的程式員和你一樣清楚運算子的優先順序。
if (a == b && c == d) // AVOID!
if ((a == b) && (c == d)) // RIGHT
6. 對於返回List/Set/Map的方法，當集合中不存在記錄時，返回空的List/Set/Map,而不是null. 在java.util.Collections類中存在3個對應的Null 物件 EMPTY_LIST, EMPTY_SET和EMPTY_Map
7. session,application變數的key值，不能只是個簡單的名字，為了避免衝突,通常需要給key值帶上包名。
如：
USER_DATA_KEY是用來儲存登陸使用者資訊的
private static final String PACKAGE_NAME = Constants.class.getName();
public static final String USER_DATA_KEY = PACKAGE_NAME + ".userData";
排版/其它
1. 代碼風格統一採用Eclipse預設的風格，請選定代碼後使用快速鍵“CTRL+SHIFT+F”格式化代碼；
2. 每行只包含一條語句.不允許在一行中出現這種情況:argv++; argc--;
3. 所有if,for,while,do while等中的語句塊都應該包含在{}裡. 這樣便於添加語句而無需擔心由於忘了加括弧而引入bug
4. 單行長度盡量避免一行的長度超過80個字元
5. 推薦一行一個聲明，因為這樣以利於寫注釋
6. 避免聲明的局部變數覆蓋上一級聲明的變數。例如，不要在內部代碼塊中聲明相同的變數名
7. 方法內的局部變數和方法的第一條語句之間使用空行間隔
8. 塊注釋（參見"5.1.1"）或單行注釋（參見"5.1.2"）之前插入空行間隔
9. 一個緊跟著括弧的關鍵字應該被空格分開.如: while ( true ){}
10. 參數列表的逗號後面要加空格。如：getBranch(String branchCode, String subbranchCode);
11. for語句中的運算式應該被空格分開 for(int I=0; I<10; I++)
12. 一元操作符和運算元之間不因該加空格，比如：負號("-")、自增("++")和自減("--")
13. 強制轉型後應該跟一個空格myMethod((byte) aNum, (Object) x);
Java編程規範
