java程式設計規範補充說明

2019-09-05 初版

一、命名規範

1. 類和介面命名：

關於字首與字尾，字首摘要用於方便區分java檔案（包括前段檔案jsp/js都應該有字首）所屬模組，比如財務以Acc開頭、工資以Salary開頭、人事Hr、物資Wz、流程Flow等，各開發組的可組長或組內成員協商而定。新表和實體類的建立也要按該要求新增字首，字首的大小寫遵守《2.軟體程式設計規範----2.1、2.2、2.3》中的規則。

字尾主要用於區分java檔案承擔的功能型別，控制層檔案Action以Action結尾；service用Service結尾，實現類用ServiceImpl結尾；工具類用Util

補充說明：新版service介面不再以字母“I”開頭，直接以各自業務字首開頭即可。

2. 方法命名：

方法中，存取屬性的方法採用setter 和 getter方法，動作方法採用動詞和動賓結構。

格式：

get + 非布林屬性名() 

is + 布林屬性名() 

set + 屬性名() 

動詞() 

動詞 + 賓語() 

示例：

public String getType(); 

public boolean isFinished(); 

public void setVisible(boolean); 

public void show(); 

public void addKeyListener(Listener);

統一部分方法名開頭：

Action頁面跳轉：to+名稱()，

Service、action或其他型別：

查詢資料：search+xxx，如查詢使用者：searchUserList()

獲取資料：get+xxx，如獲取使用者資訊：getUser()

儲存資料：save+xxx，如儲存憑證：saveVoucher()

新增記錄：add+xxx，如新增憑證：addVoucher()

刪除資料：delelte+xxx，如刪除使用者：deleteUser()

修改更新：update+xxx，如更新使用者資訊：updateUser()

檢查驗證：check+xxx，如檢查使用者編號：checkUserNo()

其他業務類操作：業務動詞+xxx，如推送資訊：pushMessage()

二、程式設計規範：

2.1、排版規範：

縮排：在方法體的開始、類和介面的定義、以及if、for、do、while、switch、case語句中的程式都要進行縮排，縮排的空格數為4個。if/for/while/switch/do 等保留字與括號之間都必須加空格，且都要加括號{}。

空格：在兩個以上的關鍵字、變數、常量進行對等操作時，它們之間的操作符之前、之後或者前後要加空格（如：int[] numArray = {1, 2, 3};）；進行非對等操作時，如果是關係密切的立即操作符（如str.toString()的圓點，!isOk的非操作符，以及遞減(--)、遞增(++)等）後不應加空格。

換行：不允許把多個短語句寫在一行中，即一行只寫一條語句。相對獨立的程式塊之間、變數說明之後必須加空行。

一個方法儘量控制在30行以內，每行控制在80個字元，超出部分則要進行換行，換行是要注意，同組織程式碼的應該在同一行，例如不能把一個完整單詞中間切成兩行顯示。

1） 第二行相對第一行縮排 4 個空格，從第三行開始，不再繼續縮排，參考示例。

2） 運算子與下文一起換行。

3） 方法呼叫的點符號與下文一起換行。

4） 在多個引數超長， 在逗號後換行。

5） 在括號前不要換行，見反例。

正例：

StringBuffer sb = new StringBuffer();

// 超過 80 個字元的情況下，換行縮排 4 個空格，並且方法前的點符號一起換行

sb.append("zi").append("xin")...

.append("huang")...

.append("huang")...

.append("huang");

反例：

StringBuffer sb = new StringBuffer();

// 超過 80 個字元的情況下，不要在括號前換行

sb.append("zi").append("xin")...append

("huang");// .append應該一起換行

// 引數很多的方法呼叫可能超過 80 個字元， 不要在逗號前換行

method(args1, args2, args3, ...

, argsX);// 逗號應在上一行

方法：一個方法應該只能進行一個操作，即一個方法只能完成一個功能，有多個的功能操作應該獨立寫成一個私有方法供其呼叫，如果需要繼承則改成保護的，如果需要外部呼叫則改為公用的。每個被呼叫的方法應該都要有返回值，告訴呼叫者執行的結果。

2.2、程式設計複雜度，建議最大規模：

1、繼承不能超過5層，

2、類的行數控制在1000行內，

3、一個類的方法數量原則上不能超過30個，

4、方法行數控制在30行內，

5、語句和表示式最大長度80字元，

6、方法引數5個，

7、註釋覆蓋率25%以上。

2.3、關於ajax請求：

所有Ajax請求，如果沒有特殊要求，返回結果應為json格式的字串。由miniui或其他的前端控制元件查詢資料或請求資料的，要轉換成前端控制元件所要求的json格式傳遞資料。向後臺獲取資料物件或資料集的，要把相應物件或集合轉成json字串後再傳遞。

其他非資料請求的Ajxa返回結果，比如檢查是否通過或儲存是否成功的結果，也應該使用json格式的字串進行傳遞。建議格式可以是格式為：

{isOk:true, data:null, resultCode:1, other:"ok", resultMessage: ""}

該實體類在：com/wxtSoft/system/common/AjaxResultJsonBean.java

三、註釋規範

註釋最大的作用是提高程式可讀性，以及記錄備忘，需要註釋的地方一定要加上註釋。註釋覆蓋率25%以上，原則上註釋不能超過50%，應該在適度範圍內。

Java有三種註釋方式：

/** 文件註釋，可以通過javadoc生成API文件 */

/* 多行註釋或塊(block)註釋 */

// 單行註釋（single-line）

說明：javadoc命令有相應javadoc標籤配合使用，詳情可檢視文件末尾的附表1

1. 【強制】檔案註釋使用塊註釋，放在檔案最頂端，即java檔案package關鍵字的上方，避免被javadoc收集，內容包含：版權說明、描述資訊、生成日期、修改日誌。

2. 【強制】類、類屬性、類方法、域、建構函式、方法的註釋必須使用 Javadoc 規範，使用文件註釋的方式，不得使用//xxx 方式。 

類和介面註釋內容應該包含：版本號、生成日期、作者、模組目的/功能、主要函式及其功能等。

3.【強制】方法的註釋內容應包含：功能描述、引數說明、返回值等。詳細參考《開發規範》

4.【強烈建議】為了增強常量，全域性變數、區域性變數和結構程式碼塊的可讀性，都應該做註釋，應該說只要不是一眼看懂的都要有註釋。

對變數的定義和分支語句（條件分支、迴圈語句等）應編寫註釋；

全域性變數要有較詳細的註釋，建議使用文件註釋，包括對其功能、取值範圍、哪些函式或過程存取它以及存取時注意事項等的說明；

註釋與所描述內容進行同樣的縮排；

修改程式碼同時更新相應的註釋，保證註釋與程式碼的一致性。不再有用的註釋要刪除。

四、防SQL注入：

如何用到拼接條件的SQL語句，只要是存在SQL注入可能的條件字串，都要做防注入處理。推薦使用apache工具包common-lang裡的工具類StringEscapeUtils的escapeSql(str)方法做處理，這是當前使用最常用的防SQL注入方式。處理過程是：先將條件字串通過StringEscapeUtils的escapeSql(str)方法處理後，再拼接到SQL語句字串中。注意：千萬不要對整個SQL用escapeSql做處理。例如下圖所示：

五、審查機制：統一程式碼風格和程式設計規範是每個軟體公司必要的工作。每個開發人員都應該嚴格遵守以上所述的開發規範。為了以上規範內持續、有效執行下來，每個小組的組長要對各自組員提交的程式碼做好審查工作。若發現程式設計不規範，則屬於開發工作未完成，相關程式碼將視為無效，要求相關開發人員重做，直到符合程式設計規範為止。

附表1：

javadoc是Sun公司提供的一個技術，它從程式原始碼中抽取類、方法、成員等註釋形成一個和原始碼配套的API幫助文件。

javadoc命令是用來生成自己API文件的，使用方式：在dos中在目標檔案所在目錄輸入javadoc +檔名.java。

此 外還有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、 {@code} {@value arg}幾個不常用的標籤，由於不常使用，我們展開敘述，感興趣的讀者可以檢視幫助文件。