文章來源：公眾號-智慧化IT系統。

編碼規範

1.明確方法功能，精確（而不是近似）地實現方法設計。如果一個功能將在多處實現，即使只有兩行程式碼，也應該編寫方法實現。

說明：

雖然為僅用一兩行就可完成的功能去編方法好象沒有必要，但用方法可使功能明確化，增加程式可讀性，亦可方便維護、測試。

2.應明確規定對介面方法引數的合法性檢查應由方法的呼叫者負責還是由介面方法本身負責，預設是由方法呼叫者負責。

說明：

對於模組間介面方法的引數的合法性檢查這一問題，往往有兩個極端現象，即：要麼是呼叫者和被呼叫者對引數均不作合法性檢查，結果就遺漏了合法性檢查這一必要的處理過程，造成問題隱患；要麼就是呼叫者和被呼叫者均對引數進行合法性檢查，這種情況雖不會造成問題，但產生了冗餘程式碼，降低了效率。

3.明確類的功能，精確（而不是近似）地實現類的設計。一個類僅實現一組相近的功能。說明：劃分類的時候，應該儘量把邏輯處理、資料和顯示分離，實現類功能的單一性。

示例：

資料類不能包含資料處理的邏輯。通訊類不能包含顯示處理的邏輯。

4.所有的資料類必須過載toString() 方法，返回該類有意義的內容。說明：父類如果實現了比較合理的toString() ， 子類可以繼承不必再重寫。

示例：

public TopoNode {     private String nodeName;     public String toString()      {         return "NodeName : " +  nodeName;      } }

5.資料庫操作、IO操作等需要使用結束close()的物件必須在try -catch-finally 的finally中close()。

6.異常捕獲後，如果不對該異常進行處理，則應該記錄日誌（針對後臺）。

說明：若有特殊原因必須用註釋加以說明。

7.自己丟擲的異常必須要填寫詳細的描述資訊。

說明：便於問題定位。

示例：

throw  new IOException("Writing data error! Data: " + data.toString());

8. 在程式中使用異常處理還是使用錯誤返回碼處理，根據是否有利於程式結構來確定，並且異常和錯誤碼不應該混合使用，推薦使用異常。說明：一個系統或者模組應該統一規劃異常型別和返回碼的含義。但是不能用異常來做一般流程處理的方式，不要過多地使用異常，異常的處理效率比條件分支低，而且異常的跳轉流程難以預測。

9.避免使用不易理解的數字，用有意義的標識來替代。涉及物理狀態或者含有物理意義的常量，不應直接使用數字，必須用有意義的靜態變數來代替。示例：

如下的程式可讀性差

if  (state == 0)

{

state = 1;

... // program  code

}

應改為如下形式

private final static int  TRUNK_IDLE = 0;private final static int TRUNK_BUSY = 1;private final static int TRUNK_UNKNOWN = -1;

if (state == TRUNK_IDLE)

{     state = TRUNK_BUSY;     ... // program code

}

10.陣列宣告的時候使用 int[] index ，而不要使用 int index[] 。說明：

11.異常捕獲儘量不要直接 catch (Exception ex) ，應該把異常細分處理。

12.不要使用難懂的技巧性很高的語句，除非很有必要時。說明：高技巧語句不等於高效率的程式，實際上程式的效率關鍵在於演算法。

註釋規範

1.在有處理邏輯的程式碼中，源程式有效註釋量必須在20％以上。

說明：註釋的原則是有助於對程式的閱讀理解，在該加的地方都加了，註釋不宜太多也不能太少，註釋語言必須準確、易懂、簡潔。

2.檔案註釋：檔案註釋寫入檔案頭部。

說明：以/* 開始

示例：

/ *

* 檔名：[檔名]

* 作者：〈版權〉

* 描述：〈描述〉

* 修改人：〈修改人〉

* 修改時間：YYYY-MM-DD

 * 修改內容：〈修改內容〉  */

說明：每次修改後在檔案頭部寫明修改資訊。

示例：

/ *

* 檔名：LogManager.java

* 版權：Copyright 2000-2001 Huawei Tech. Co. Ltd.  All Rights Reserved.

* 描述： WIN V200R002 WEBSMAP 通用日誌系統

* 修改人：張三

* 修改時間：2001-02-16

* 修改內容：新增

* 修改人：李四

* 修改時間：2001-02-26

* 修改內容：。。。。。。

* 修改人：王五

* 修改時間：2001-03-25

* 修改內容：。。。。。。

 */

3.類和介面的註釋：該註釋放在class定義之前，using或package關鍵字之後。

示例：

package com. websmap.comm;

/**

 * 註釋內容

 */ public class CommManager

4.類和介面的註釋內容：類的註釋主要是一句話功能簡述、功能詳細描述，說明：可根據需要列出：版本號、生成日期、作者、內容、功能、與其它類的關係等。

格式：

/ *

 * 〈一句話功能簡述〉

* 〈功能詳細描述〉

* @author [作者]

* @version [版本號, YYYY-MM-DD]

* @see [相關類/方法]

* @since [產品/模組版本]

* @deprecated

*/

說明：描述部分說明該類或者介面的功能、作用、使用方法和注意事項，每次修改後增加作者和更新版本號和日期，@since 表示從那個版本開始就有這個類或者介面，@deprecated 表示不建議使用該類或者介面。

示例：

/ *

* LogManager 類集中控制對日誌讀寫的操作。

*全部為靜態變數和靜態方法，對外提供統一介面。分配對應日誌型別的讀寫器，讀取或寫入符合條件的日誌紀錄。

* @author 張三，李四，王五

* @version 1.2, 2001-03-25

* @see LogIteraotor

* @see BasicLog

* @since CommonLog1.0

*/

5.類屬性、公有和保護方法註釋：寫在類屬性、公有和保護方法上面。用//來註釋,需要對齊被註釋程式碼。

示例：

/ /註釋內容

private  String logType

6.成員變數註釋內容：成員變數的意義、目的、功能，可能被用到的地方。用//來註釋,需要對齊被註釋程式碼

7.公有和保護方法註釋內容：列出方法的一句話功能簡述、功能詳細描述、輸入引數、輸出引數、返回值、違例等。格式：

/ **

*〈一句話功能簡述〉

*〈功能詳細描述〉

* @param [引數1] [引數1說明]

* @param [引數2] [引數2說明]

* @return [返回型別說明]

* @exception/throws [違例型別] [違例說明]

* @see [類、類#方法、類#成員]

 * @deprecated

*/

說明：@since 表示從那個版本開始就有這個方法；@exception或throws 列出可能出現的異常；@deprecated 表示不建議使用該方法。

8.對於方法內部用throw語句丟擲的異常，必須在方法的註釋中標明，對於所呼叫的其他方法所丟擲的異常，選擇主要的在註釋中說明。對於非RuntimeException ，即throws子句宣告會丟擲的異常，必須在方法的註釋中標明。

說明：

異常註釋用@exception或@throws表示，在JavaDoc中兩者等價，但推薦用@exception標註Runtime 異常，@throws標註非Runtime 異常。異常的註釋必須說明該異常的含義及什麼條件下丟擲該異常。

9.註釋應與其描述的程式碼相近，對程式碼的註釋應放在其上方或右方（對單條語句的註釋）相鄰位置，不可放在下面，如放於上方則需與其上面的程式碼用空行隔開。

10.註釋的排版，按照上述示例來展示。

11.註釋應該放在被註釋的程式碼前面，分行展示，但中間不留空行。

12.對變數的定義和分支語句（條件分支、迴圈語句等）必須編寫註釋。

說明：分支語句往往是程式實現某一特定功能的關鍵。

13.邊寫程式碼邊註釋，修改程式碼同時修改相應的註釋，以保證註釋與程式碼的一致性。不再有用的註釋要刪除。

14.註釋的內容要清楚、明瞭，含義準確，防止註釋二義性。說明：錯誤的註釋不但無益反而有害。

15.避免在註釋中使用縮寫，特別是不常用縮寫。說明：在使用縮寫時或之前，應對縮寫進行必要的說明。

公眾號-智慧化IT系統。每週都有技術文章推送，包括原創技術乾貨，以及技術工作的心得分享。掃描下方關注。