Java 編程規範

時間 2019-12-04

標籤 java 編程規範欄目 Java 简体版

原文原文鏈接

Java 編程規範 html

排版java

規則node

程序塊要採用縮進風格編寫，縮進的空格數爲4個，不容許使用TAB縮進。(1.42+)程序員

說明：縮進使程序更易閱讀，使用空格縮進能夠適應不一樣操做系統與不一樣開發工具。web

分界符（如大括號‘{’和‘}’）應各獨佔一行，同時與引用它們的語句左對齊。在函數體的開始、類和接口的定義、以及if、for、do、while、switch、case語句中的程序或者static、,synchronized等語句塊中都要採用如上的縮進方式。(1.42+)算法

示例:數據庫

if (a>b)編程

{數組

doStart();app

}

較長的語句、表達式或參數（>80字符）要分紅多行書寫，長表達式要在低優先級操做符處劃分新行，操做符放在新行之首，劃分出的新行要進行適當的縮進，使排版整齊，語句可讀。(1.42+)

示例：

if (logger.isDebugEnabled())

{

logger.debug("Session destroyed,call-id"

+ event.getSession().getCallId());

}

不容許把多個短語句寫在一行中，即一行只寫一條語句(1.42+)

說明：閱讀代碼更加清晰

示例：以下例子不符合規範。

Object o = new Object(); Object b = null;

if, for, do, while, case, switch, default 等語句自佔一行，且if, for, do, while,switch等語句的執行語句不管多少都要加括號{},case 的執行語句中若是定義變量必須加括號{}。(1.42+)

說明：閱讀代碼更加清晰，減小錯誤產生

示例：

if (a>b)

{

doStart();

}

case x:

{

int i = 9;

}

相對獨立的程序塊之間、變量說明以後必須加空行。 (1.42+)

說明:閱讀代碼更加清晰

示例：

if(a > b)

{

doStart();

}

//此處是空行

return;

在兩個以上的關鍵字、變量、常量進行對等操做時，它們之間的操做符以前、以後或者先後要加空格；進行非對等操做時，若是是關係密切的當即操做符（如.），後不該加空格。(1.42+)

說明：閱讀代碼更加清晰

示例：

if (a == b)

{

objectA.doStart();

}

a *= 2;

建議

類屬性和類方法不要交叉放置，不一樣存取範圍的屬性或者方法也儘可能不要交叉放置。(1.42+)

格式：

類定義

{

類的公有屬性定義

類的保護屬性定義

類的私有屬性定義

類的公有方法定義

類的保護方法定義

類的私有方法定義

}

修飾詞按照指定順序書寫：[訪問權限][static][final] 。(1.42+)

示例：

public static final String str = 「abc」;

註釋

規則

源程序註釋量必須在30％以上。(1.42+)

說明：因爲每一個文件的代碼註釋不必定均可以達到30%，建議以一個系統內部模塊做爲單位進行檢查

包的註釋：寫入一個名爲 package.html 的HTML格式的說明文件放入包所在路徑。包的註釋內容：簡述本包的做用、詳細描述本包的內容、產品模塊名稱和版本、公司版權。(1.42+)

說明：方便JavaDoc收集，方便對包的瞭解

示例：

com/huawei/iin/websmap/comm/package.html

<html>

<body>

一句話簡述。

詳細描述。

產品模塊名稱和版本

公司版權信息

</body>

</html>

示例：

<html>

<body>

爲 WEBSMAP 提供通訊類，上層業務使用本包的通訊類與 SMP-B 進行通訊。

詳細描述。。。。。。。。

IIN V100R001 WEBSMAP

(C) 版權全部 2000-2001 華爲技術有限公司

</body>

</html>

類和接口的註釋放在class 或者 interface 關鍵字以前，import 關鍵字以後。註釋主要是一句話功能簡述與功能詳細描述。類註釋使用「/** */」註釋方式(1.42+)

說明：方便JavaDoc收集,沒有import可放在package以後。註釋可根據須要列出：做者、內容、功能、與其它類的關係等。功能詳細描述部分說明該類或者接口的功能、做用、使用方法和注意事項，每次修改後增長做者和更新版本號和日期，@since 表示從那個版本開始就有這個類或者接口，@deprecated 表示不建議使用該類或者接口。

/**

* 〈一句話功能簡述〉

* 〈功能詳細描述〉

* @author [做者]（必須）

* @see [相關類/方法]（可選）

* @since [產品/模塊版本] （必須）

* @deprecated （可選）

示例：

package com.huawei.iin.logwebsmap.comm;

import java.util.*;

/**

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

* 所有爲靜態變量和靜態方法，對外提供統一接口。分配對應日誌類型的讀寫器，

* 讀取或寫入符合條件的日誌紀錄。

* @author 張三，李四，王五

* @see LogIteraotor

* @see BasicLog

* @since CommonLog1.0

public class LogManager

類屬性(成員變量)、公有和保護方法註釋：寫在類屬性、公有和保護方法上面，註釋方式爲「/** */」.(1.42+)

示例：

/**

* 註釋內容

private String logType;

/**

* 註釋內容

public void write()

公有和保護方法註釋內容：列出方法的一句話功能簡述、功能詳細描述、輸入參數、輸出參數、返回值、異常等。(1.42+)

格式：

/**

* 〈一句話功能簡述〉

* 〈功能詳細描述〉

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

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

* @return [返回類型說明]

* @exception/throws [異常類型] [異常說明]

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

* @since [起始版本]

* @deprecated

說明：@since 表示從那個版本開始就有這個方法，若是是最第一版本就存在的方法無需說明；@exception 或throws 列出可能仍出的異常；@deprecated 表示不建議使用該方法。

示例：

/**

* 根據日誌類型和時間讀取日誌。

* 分配對應日誌類型的LogReader，指定類型、查詢時間段、條件和反覆器緩衝數，

* 讀取日誌記錄。查詢條件爲null或0的表示沒有限制，反覆器緩衝數爲0讀不到日誌。

* 查詢時間爲左包含原則，即 [startTime, endTime) 。

* @param logTypeName 日誌類型名（在配置文件中定義的）

* @param startTime 查詢日誌的開始時間

* @param endTime 查詢日誌的結束時間

* @param logLevel 查詢日誌的級別

* @param userName 查詢該用戶的日誌

* @param bufferNum 日誌反覆器緩衝記錄數

* @return 結果集，日誌反覆器

* @since 1.2

public static LogIterator read(String logType, Date startTime, Date endTime, int logLevel, String userName, int bufferNum)

對於方法內部用throw語句拋出的異常，必須在方法的註釋中標明，對於所調用的其餘方法所拋出的異常，選擇主要的在註釋中說明。對於非RuntimeException，即throws子句聲明會拋出的異常，必須在方法的註釋中標明。(1.42+)

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

註釋應與其描述的代碼相近，對代碼的註釋應放在其上方，並與其上面的代碼用空行隔開，註釋與所描述內容進行一樣的縮排。(1.42+)

說明：可以使程序排版整齊，並方便註釋的閱讀與理解。

示例：

* 註釋

public void example2( )

{

// 註釋

CodeBlock One

// 註釋

CodeBlock Two

}

* 註釋

public void example( )

{

// 註釋

CodeBlock One

// 註釋

CodeBlock Two

}

對於switch語句下的case語句，必須在每一個case分支結束前加上break語句。(1.42+)

說明：break才能真正表示該switch執行結束，否則可能會進入該case之後的分支。至於語法上合法的場景「一個case後進入下一個case處理」，應該在編碼設計上就避免。

修改代碼同時修改相應的註釋，以保證註釋與代碼的一致性。再也不有用的註釋要刪除。(1.42+)

註釋的內容要清楚、明瞭，含義準確，防止註釋二義性。(1.42+)

說明：錯誤的註釋不但無益反而有害。

避免在註釋中使用縮寫，特別是不經常使用縮寫。(1.42+)

說明：在使用縮寫時或以前，應對縮寫進行必要的說明。

對重載父類的方法必須進行@Override聲明(5.0+)

說明：可清楚說明此方法是重載父類的方法，保證重載父類的方法時不會由於單詞寫錯而形成錯誤(寫錯方法名或者參數個數，類型都會編譯沒法經過)

示例：

@Override

public void doRequest(SipServletRequest req) throws ServletException,

IOException

建議

避免在一行代碼或表達式的中間插入註釋。(1.42+)

說明：除非必要，不該在代碼或表達中間插入註釋，不然容易使代碼可理解性變差。

在代碼的功能、意圖層次上進行註釋，提供有用、額外的信息。(1.42+)

說明：註釋的目的是解釋代碼的目的、功能和採用的方法，提供代碼之外的信息，幫助讀者理解代碼，防止不必的重複註釋信息。

示例：以下注釋意義不大。

// 若是 receiveFlag 爲真

if (receiveFlag)

而以下的註釋則給出了額外有用的信息。

// 若是從連結收到消息

if (receiveFlag)

對關鍵變量的定義和分支語句（條件分支、循環語句等）必須編寫註釋。(1.42+)

說明：這些語句每每是程序實現某一特定功能的關鍵，對於維護人員來講，良好的註釋幫助更好的理解程序，有時甚至優於看設計文檔。

註釋應考慮程序易讀及外觀排版的因素，使用的語言如果中、英兼有的，建議多使用中文，除非能用很是流利準確的英文表達。中文註釋中需使用中文標點。方法和類描述的第一句話儘可能使用簡潔明瞭的話歸納一下功能，而後加以句號。接下來的部分能夠詳細描述。(1.42+)

說明：註釋語言不統一，影響程序易讀性和外觀排版，出於對維護人員的考慮，建議使用中文。JavaDoc工具收集簡介的時候使用選取第一句話。

方法內的單行註釋使用 //。(1.42+)

說明：調試程序的時候能夠方便的使用 /* 。。。*/ 註釋掉一長段程序。

一些複雜的代碼須要說明。(1.42+)

示例：這裏主要是對閏年算法的說明。

//1. 若是能被4整除，是閏年；

//2. 若是能被100整除，不是閏年；

//3. 若是能被400整除，是閏年。

使用Html標籤使JavaDoc生成更加美觀。(1.42+)

示例：

/**

* Returns a hash code for this string. The hash code for a

* <code>String</code> object is computed as

* <blockquote><pre>

* s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1]

* </pre></blockquote>

* using <code>int</code> arithmetic, where <code>s[i]</code> is the

* ith character of the string, <code>n</code> is the length * of

* the string, and <code>^</code> indicates exponentiation.

* (The hash value of the empty string is zero.)

* @return a hash code value for this object.

public int hashCode()

生成後的JavaDoc

命名

規則

類名和接口使用類意義完整的英文描述，每一個英文單詞的首字母使用大寫、其他字母使用小寫的大小寫混合法。(1.42+)

示例：OrderInformation, CustomerList, LogManager, LogConfig, SmpTransaction

方法名使用類意義完整的英文描述：第一個單詞的字母使用小寫、剩餘單詞首字母大寫其他字母小寫的大小寫混合法。(1.42+)

示例：

private void calculateRate();

public void addNewOrder();

方法中，存取屬性的方法採用setter 和 getter方法，動做方法採用動詞和動賓結構。(1.42+)

格式：

get + 非布爾屬性名()

is + 布爾屬性名()

set + 屬性名()

動詞()

動詞 + 賓語()

示例：

public String getType();

public boolean isFinished();

public void setVisible(boolean);

public void show();

public void addKeyListener(Listener);

屬性名使用意義完整的英文描述，第一個單詞的字母使用小寫，剩餘單詞首字母大寫其他字母小寫的大小寫混合法。屬性名不能與方法名相同。(1.42+)

示例：

private customerName;

private orderNumber;

private smpSession;

常量名使用全大寫的英文描述，英文單詞之間用下劃線分隔開，而且使用 static final修飾。(1.42+)

示例：

public static final int MAX_VALUE = 1000;

public static final String DEFAULT_START_DATE = "2001-12-08";

建議

包名採用域後綴倒置的加上自定義的包名，採用小寫字母，都應該以com.huawei開頭(不包括一些特殊緣由)。在部門內部應該規劃好包名的範圍，防止產生衝突。部門內部產品使用部門的名稱加上模塊名稱。產品線的產品使用產品的名稱加上模塊的名稱。(1.42+)

說明：除特殊緣由包結構都必須以com.huawei開頭，若是由於OEM合做等關係，能夠不作要求。

格式：

com.huawei.產品名.模塊名稱

示例：

融合WEBSMAP包名 com.huawei.iin.websmap

經過對函數或過程、變量、結構等正確的命名以及合理地組織代碼的結構，使代碼成爲自注釋的。(1.42+)

說明：清晰準確的函數、變量等的命名，可增長代碼可讀性，並減小沒必要要的註釋。

經常使用組件類的命名以組件名加上組件類型名結尾。(1.42+)

示例：

Application 類型的，命名以App 結尾——MainApp

Frame 類型的，命名以Frame 結尾——TopoFrame

Panel 類型的，建議命名以Panel 結尾——CreateCircuitPanel

Bean 類型的，建議命名以Bean 結尾——DataAccessBean

EJB 類型的，建議命名以EJB 結尾——DBProxyEJB

Applet 類型的，建議命名以Applet 結尾——PictureShowApplet

若是函數名超過15 個字母，可採用以去掉元音字母的方法或者以行業內約定俗成的縮寫方式縮寫函數名。(1.42+)

示例：

getCustomerInformation() 改成 getCustomerInfo()

準確地肯定成員函數的存取控制符號:只是該類內部調用的函數使用 private 屬性，繼承類可使用的使用protected屬性，同包類能夠調用的使用默認屬性(不加屬性控制符號)，對外公開的函數使用public屬性(1.42+)

示例：

protected void getUserName()

{

。。。。。。

}

private void calculateRate()

{

。。。。。。

}

含有集合意義的屬性命名，儘可能包含其複數的意義。(1.42+)

示例：

customers, orderItems

編碼

規則

數據庫操做、IO操做等須要使用結束close()的對象必須在try -catch-finally 的finally中close()，若是有多個IO對象須要close()，須要分別對每一個對象的close()方法進行try-catch,防止一個IO對象關閉失敗其餘IO對象都未關閉。(1.42+)

示例：

try

{

// ... ...

}

catch(IOException ioe)

{

//... ...

}

finally

{

try

{

out.close();

}

catch (IOException ioe)

{

//... ...

}

try

{

in.close();

}

catch (IOException ioe)

{

//... ...

}

系統非正常運行產生的異常捕獲後，若是不對該異常進行處理，則應該記錄日誌。 (1.42+)

說明：此規則指一般的系統非正常運行產生的異常，不包括一些基於異常的設計。如有特殊緣由必須用註釋加以說明。

示例：

try

{

//.... ...

}

catch (IOException ioe)

{

logger.error(ioe);

}

本身拋出的異常必需要填寫詳細的描述信息。(1.42+)

說明：便於問題定位。

示例：

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

運行時異常使用RuntimeException的子類來表示，不用在可能拋出異常的方法聲明上加throws子句。非運行期異常是從Exception繼承而來的，必須在方法聲明上加throws子句。(1.42+)

說明：

非運行期異常是由外界運行環境決定異常拋出條件的異常，例如文件操做，可能授權限、磁盤空間大小的影響而失敗，這種異常是程序自己沒法避免的，須要調用者明確考慮該異常出現時該如何處理方法，所以非運行期異常必須有throws子句標出，不標出或者調用者不捕獲該類型異常都會致使編譯失敗，從而防止程序員自己疏忽。

運行期異常是程序在運行過程當中自己考慮不周致使的異常，例如傳入錯誤的參數等。拋出運行期異常的目的是防止異常擴散，致使定位困難。所以在作異常體系設計時要根據錯誤的性質合理選擇自定義異常的繼承關係。

還有一種異常是Error 繼承而來的，這種異常由虛擬機本身維護，表示發生了致命錯誤，程序沒法繼續運行例如內存不足。咱們本身的程序不該該捕獲這種異常，而且也不該該建立該種類型的異常。

在程序中使用異常處理仍是使用錯誤返回碼處理，根據是否有利於程序結構來肯定，而且異常和錯誤碼不該該混合使用，推薦使用異常。(1.42+)

說明：

一個系統或者模塊應該統一規劃異常類型和返回碼的含義。

可是不能用異常來作通常流程處理的方式，不要過多地使用異常，異常的處理效率比條件分支低，並且異常的跳轉流程難以預測。

注意：Java 5.0 程序內部的錯誤碼可使用枚舉來表示。

注意運算符的優先級，並用括號明確表達式的操做順序，避免使用默認優先級。(1.42+)

說明：防止閱讀程序時產生誤解，防止因默認的優先級與設計思想不符而致使程序出錯。

示例：

下列語句中的表達式

word = (high << 8) | low (1)

if ((a | b) && (a & c)) (2)

if ((a | b) < (c & d)) (3)

若是書寫爲

high << 8 | low

a | b && a & c

a | b < c & d

（1）（2）雖然不會出錯，但語句不易理解；（3）形成了判斷條件出錯。

避免使用不易理解的數字，用有意義的標識來替代。涉及物理狀態或者含有物理意義的常量，不該直接使用數字，必須用有意義的靜態變量或者枚舉來代替。使用異常來表示方法執行錯誤，而不是使用C++的錯誤返回碼方式。(1.42+)

示例：以下的程序可讀性差。

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

}

注意：Java 5.0 下建議使用枚舉來表示。

異常：

public void function()

{

...

throw new RuntimeException(「。。。」);

}

數組聲明的時候使用 int[] index ，而不要使用 int index[] 。(1.42+)

說明：使用int index[] 格式使程序的可讀性較差，int [] index 表示聲明瞭一個int數組(int [])叫作index

示例：

以下程序可讀性差：

public int getIndex()[]

{

....

}

以下程序可讀性好：

public int[] getIndex()

{

....

}

不要使用 System.out 與 System.err 進行控制檯打印，應該使用工具類(如：日誌工具)進行統一記錄或者打印。(1.42+)

說明：代碼發佈的時候能夠統一關閉控制檯打印，代碼調試的時候又能夠打開控制檯打印，方便調試。

用調測開關來切換軟件的DEBUG版和正式版，而不要同時存在正式版本和DEBUG版本的不一樣源文件，以減小維護的難度。 (1.42+)

集合必須指定模板類型(5.0+)

說明：方便程序閱讀，除去強制轉換代碼

示例：

Map<String,MyObject> map = new HashMap<String,MyObject>();

一個文件不要定義兩個類(並不是指內部類)。(1.42+)

說明：方便程序的閱讀與代碼的維護

全部的數據類必須覆寫toString()、hashCode()、equals() 方法，toString()方法返回該類有意義的內容。(1.42+)

說明：方便數據類的比較，父類若是實現了比較合理的toString() ，子類能夠繼承沒必要再重寫。

hashCode與equals可使用eclipse自動生成。

示例：

public TopoNode

{

private String nodeName;

public String toString()

{

return "NodeName : " + nodeName;

}

判斷語句不要使用」* == true」來判斷爲真

說明：方便閱讀，減小沒有必要的計算

如下錯誤：

if (ok == true)

{

……

}

如下正確：

if (ok)

{

……

}

不要寫沒有必要的向上強制轉型。(1.42+)

說明：不必寫的向上強制轉型會浪費性能，增長代碼閱讀難度

示例：

如下錯誤：

FileInputStream fis = new FileInputStream(f);

InputStream is = (InputStream)fis;

建議

記錄異常不要保存exception.getMessage()，而要記錄exception.toString()，通常可經過日誌工具記錄完整的異常堆棧信息。(1.42+)

說明：NullPointException拋出時經常描述爲空，這樣每每看不出是出了什麼錯。

示例：

try

{

...

}

catch (FileNotFoundException e)

{

logger.error(e);

}

一個方法不該拋出太多類型的異常。(1.42+)

說明：若是程序中須要分類處理，則將異常根據分類組織成繼承關係。若是確實有不少異常類型首先考慮用異常描述來區別，throws/exception子句標明的異常最好不要超過三個。

異常捕獲儘可能不要直接 catch (Exception ex)，應該把異常細分處理。(1.42+)

說明：能夠設計更合理異常處理分支

若是多段代碼重複作同一件事情，那麼在方法的劃分上可能存在問題。(1.42+)

說明：若此段代碼各語句之間有實質性關聯而且是完成同一件功能的，那麼可考慮把此段代碼構形成一個新的方法。

集合中的數據若是不使用了應該及時釋放，尤爲是可重複使用的集合。(1.42+)

說明：因爲集合保存了對象的引用，虛擬機的垃圾收集器就不會回收。

源程序中關係較爲緊密的代碼應儘量相鄰。(1.42+)

說明：便於程序閱讀和查找。

示例：矩形的長與寬關係較密切，放在一塊兒。

rect.length = 10;

rect.width = 5;

不要使用難懂的技巧性很高的語句，除非頗有必要時。(1.42+)

說明：高技巧語句不等於高效率的程序，實際上程序的效率關鍵在於設計與算法。

明確方法功能，精確（而不是近似）地實現方法設計。一個函數僅完成一件功能，即便簡單功能也編寫方法實現。(1.42+)

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

應明確規定對接口方法參數的合法性檢查應由方法的調用者負責仍是由接口方法自己負責，缺省是由方法調用者負責。(1.42+)

說明：對於模塊間接口方法的參數的合法性檢查這一問題，每每有兩個極端現象，即：要麼是調用者和被調用者對參數均不做合法性檢查，結果就遺漏了合法性檢查這一必要的處理過程，形成問題隱患；要麼就是調用者和被調用者均對參數進行合法性檢查，這種狀況雖不會形成問題，但產生了冗餘代碼，下降了效率。

儘可能使用Java 5.0新循環寫法。(5.0+)

說明：代碼更加簡潔

示例：

ArrayList<String> list = new ArrayList<String>();

list.add...

for(String str:list)

{

System.out.println(str);

}

使用Java 5.0枚舉來替代之前用數字與字符串的同等目的的操做。(5.0+)

說明：Java 5.0之前沒有枚舉，你們都用數字或者字符串作枚舉一樣功能的事情

示例：

public enum EnumDemo

{

ERROR,INFO,DEBUG

}

In other function：

EnumDemo t = EnumDemo.DEBUG;

if (t == EnumDemo.ERROR)

{

。。。。。。

}

interface 中定義的常量不要寫public、static、final的修飾詞，方法不要寫public修飾詞。(1.42+)

說明：更加簡潔

示例：

public interface InterfaceT

{

String TT = "abcl";

void doStart();

}

新起一個線程，都要使用Thread.setName(「…」)設置線程名。

說明：性能測試時可對線程狀態進行監控，異常時也能夠知道異常發生在哪一個線程中

性能與可靠性

規則

對Debug，Info級別日誌輸出前必須對當前的調試等級先進行判斷。(1.42+)

說明：日誌通常都會有很多字符串的處理，若是不是Debug級別就沒有必要進行處理

示例：

if (logger.debugEnable())

{

logger.debug(「request : 」 + request.getMethod());

}

數組複製使用System.arraycopy(*) 。(1.42+)

說明：更好的性能

不要使用循環將集合轉爲數組，可使用集合的toArray()方法。(1.42+)

說明：更好的性能，代碼更加簡潔

示例：

ArrayList list = new ArrayList();

list.add....

String [] array = new String[list.size()];

list.toArray(array);

大量字符串的相加等於處理應該使用StringBuffer。(1.42+)

說明：大量的String相加等於處理性能消耗較多。「大量」通常指5次「+=」以上或者在循環中進行字符串+=操做。

示例：

不推薦：

String str = 「」;

str += 」a」;

str += 」b」;