JAVA程序員不得不留意的編碼規范

01 規范存在的意義

應用編碼規范對于軟件本身和軟件開發職員而言尤為重要，有以下幾個原因：

1. 好的編碼規范可以盡可能的減少一個軟件的維護本錢 , 并且幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發職員來維護；
2. 好的編碼規范可以改善軟件的可讀性，可以讓開發職員盡快而徹底地理解新的代碼；
3. 好的編碼規范可以最大限度的進步團隊開發的合作效率；
4. 長期的規范性編碼還可以讓開發職員養成好的編碼習慣，甚至鍛煉出更加嚴謹的思維；

02 命名規范

1. 一般概念

• 盡量使用完整的英文描述符
• 采用適用于相關領域的術語
• 采用大小寫混合使名字可讀
• 盡量少用縮寫，但假如用了，必須符合整個工程中的同一定義
• 避免使用長的名字（小于 15 個字母為正常選擇）
• 避免使用類似的名字，或者僅僅是大小寫不同的名字
• 避免使用下劃線（除靜態常量等）

2. 標識符類型說明

（1） 包（ Package ）的命名

Package 的名字應該采用完整的英文描述符，都是由一個小寫單詞組成。并且包名的前綴總是一個頂級域名， 通常是 com、edu、gov、mil、net、org 等；

如：com.yjhmily.test

（2） 類（ Class ）的命名

類名應該是個一名詞，采用大小寫混合的方式，每個單詞的首字母大寫。盡量保證類名簡潔而富于描述。

使用完整單詞，避免縮寫詞 ( 除非工程內有同一縮寫規范或該縮寫詞被更廣泛使用，像 URL ， HTML)

如：FileDescription

（3） 接口（ Intece ）的命名基本與 Class 的命名規范類似。在滿足 Classd 命名規則的基礎之上，保證開頭第一個字母為 ”I”， 便于與普通的 Class區別開。實在現類名稱取接口名的第二個字母到最后，且滿足類名的命名規范；

如：IMenuEngine

（4） 枚舉（ Enum ）的命名

基本與 Class 的命名規范類似。在滿足 Classd 命名規則的基礎之上，保證開頭第一個字母為 ”E” ， 便于與普通的 Class區別開。

如：EUserRole

（5） 異常（ Exception ）的命名

異常（ Exception ） 通常采用字母 e 表示異常，對于自定義的異常類，其后綴必須為 Exception

如：BusinessException

（6）方法（ Method ）的命名

方法名是一個動詞，采用大小寫混合的方式，第一個單詞的首字母小寫，其后單詞的首字母大寫。

方法名盡可能的描述出該方法的動作行為。返回類型為 Boolean 值的方法一般由“ is ”或“ has ”來開頭

如：

getCurrentUser() 
addUser()
hasAuthority()

（7） 參數（ Param ）的命名

第一個單詞的首字母小寫，其后單詞的首字母大寫。參數目名不答應以下劃線或美元符號開頭， 固然這在語法上是答應的。參數名應簡短且富于描述。

如：public UserContext getLoginUser(String loginName);

（8）常量字段 （ Constants ）的命名

靜態常量字段（ static final ） 全部采用大寫字母，單詞之間用下劃線分隔；

如：

public static final Long FEEDBACK;
public static Long USER_STATUS;

03 注釋規范

一個很好的可遵循的有關注釋的經驗法則是：

問問你自己，你假如從未見過這段代碼，要在公道的時間內有效地明白這段代碼，你需要一些什么信息？？？

1. 一般概念

• 注釋應該增加代碼的清楚度
• 保持注釋的簡潔
• 在寫代碼之前或同時寫注釋
• 注釋出為什么做了一些事，而不僅僅是做了什么

2. 注釋哪些部分

Java 文件：必須寫明版權信息以及該文件的創建時間和作者；

類：類的目的、即類所完成的功能，以及該類創建的時間和作者名稱；多人一次編輯或修改同一個類時，應在作者名稱處出現多人的名稱；

接口： 在滿足類注釋的基礎之上，接口注釋應該包含設置接口的目的、它應如何被使用以及如何不被使用。在接口注釋清楚的條件下對應的實現類可以不加注釋；

方法注釋： 對于設置 (Set 方法 ) 與獲取 (Get 方法 ) 成員的方法，在成員變量已有說明的情況下，可以不加注釋；普通成員方法要求說明完成什么功能，參數含義是什么且返回值什么；另外方法的創建時間必須注釋清楚，為將來的維護和閱讀提供寶貴線索；

方法內部注釋： 控制結構，代碼做了些什么以及為什么這樣做，處理順序等，特別是復雜的邏輯處理部分，要盡可能的給出具體的注釋；

參數： 參數含義、及其它任何約束或條件條件；

屬性： 字段描述；

局部 ( 中間 ) 變量： 無特別意義的情況下不加注釋；

3. 注釋格式

遵循工程規定的同一注釋格式，一般情況下會以 codetemplates.xml 格式的文件導進 IDE(Eclipse) 或者用Eclipse默認的；

04 代碼格式規范

遵循工程規定的同一代碼格式，一般情況下直接使用 IDE(Eclipse) 自帶的默認代碼格式對代碼進行格式化；

05 其他規范

JSP 文件命名

用完整的英文描述說明 JSP 所完成的功能，盡可能包括一個生動的動詞，第一個字母小寫，

如： viewMessage.jsp 、editUser.jsp 等。

06 工程特有命名規范

1. 持久層

• Hibernate 映射文件及實體與數據庫表名稱完全對應；

如： Advertisement.hbm.xml 、 Advertisement.java

• 數據訪問 DAO

DAO 接口和實現類名稱必須完全符合正常接口和實現類的命名規則，且最后以 ”DAO” 結尾DAO 內的數據訪問方法必須足夠抽象的描述出對數據庫的基本 CRUD 操縱；
如： ICrossAdDAO( 接口 ) 、 CrossAdDAO( 實現類 )

• 各種操縱數據庫的 HQL 配置文件

HQL 文件的個數原則上與系統的 Services 層的服務個數相等，且以服務名稱命名 HQL 文件；
如： resource.hbm.xml

2. 服務層

（1）服務接口和實現

服務接口和實現類必須完全符合正常接口和實現類的命名規則；以工程定義的服務名為主體， 并同一以 ”Serv” 結尾
如： IResourceServ( 服務接口 ) 、 ResourceServ( 接口實現類 )

（2）服務接口方法

方法名是一個動詞，采用大小寫混合的方式，第一個單詞的首字母小寫，其后單詞的首字母大寫。
方法名盡可能的描述出該方法的動作行為。

• 返回類型為 Boolean 值：用“ is ”或“ has ”來開頭
• 得到某數據： get+ 數據描述名詞復數 + 數據類型；
• 得到所有數據： get+All+ 數據描述名詞復數 + 數據類型；
• 通過 XXX 得到 / 查詢某數據： get/query+ 數據描述名詞復數 + 數據類型 +By+ 條件；
• 添加某數據： save/add+ 數據描述名詞 ()
• 更新某數據： save/update+ 數據描述名詞；
• 刪除某數據： delete/remove+ 數據描述名詞；

（3）業務對象

業務名稱 +BO

（4）查詢參數對象

凡是繼續 Abst***QuerySpec 的查詢參數類全部滿足以下規則：

• Query+ 所要查詢的數據描述名詞 +Spec
  
• 作為參數傳進時，參數名必須為：所要查詢的數據描述名詞 +Spec

如： QueryProgramSpec

3. MVC 層

（1）Action 控制層

Action 類名：功能模塊名稱 +Action ；
Actoin 方法名稱盡可能的描述出頁面遷移的往向

如： LoginAction( 登錄用 action) ， toWelcome( 轉向歡迎頁的 action 方法 )
（2）資源文件

系統全局資源文件： globalMessages_+ 字符編碼類型 +.properties
功能模塊內部的資源文件： package.properties

4. Spring 配置文件

（1） Action 相關配置文件

文件目錄： WebRoot/WEB-INF/spring/action/功能模塊名稱 +_ApplicationContext.xml

（2）Services 相關配置文件

文件目錄： WebRoot/WEB-INF/spring/services/Services_ApplicationContext.xml

（3）全局性配置文件

文件目錄： WebRoot/WEB-INF/spring/工程名+_ApplicationContext.xml

（4）JSP 文件

采用完整的英文描述說明 JSP 所完成的功能，盡可能包括一個生動的動詞，第一個字母小寫，

如： viewMessage.jsp 、editUser.jsp 等。

07 應用命名總結

所有文件，變量同一采用英文單詞表示。盡量避免簡寫和縮寫。

1.  java類

java類根據java規范采用駝峰標示，java類首字母大寫，類名中的各個單詞首字母都大寫。

Java類代表現實世界的一個事物，類名詞最好是一個名詞。最好采用現實的名稱。如員工用Employee，而不是Employ避免歧義。最好不是用縮寫empl等。

• 應用軟件中經常應用分層，每一層的類的名稱盡量帶上該層后綴。
• 推薦實體類沒有后綴名。
• 數據層使用SQLMapper后綴。
• 數據層查詢參數為Param
• 服務層使用Service
• Web層使用Packager
• Web層form表單后綴為Form

比如員工模塊，分別為Employee(實體)，EmployeeSQLMapper(數據層)，EmployeeService(服務層)，EmployeePackager(web層)

常用英文名稱(最好能整理一份常用詞匯詞典)

• 員工:employee
• 部分:department

2.  字段

根據java駝峰標示命名法，java字段以首字母以小寫開頭，每個單詞首字母大寫（第一個單詞除外）。

字段表示現實中一個事物的屬性在類中的名稱，最好用名詞。字段名稱應采用最精確的單詞，盡量采用一個單詞。沒有必要把類名掛在字段前面，如employee的id字段，直接可以用id，不用使用employeeId，假如出現兩個字段可能產生歧義，可以增加描述性單詞來區分。

字段命名最好能看詞識意。

3. 方法

方法表示一種行為，它代表一種動作，最好是一個動詞或者動詞詞組或者第一個單詞為一個動詞。

屬性方法，get/set開頭，其后跟字段名稱，字段名稱首字母大寫。

數據層方法，只能以insert（插進）,delete（刪除）,update（更新）,select（查找）,count（統計）開頭，其他層方法避免以這個5個單詞開頭，以免造成誤解。

服務層方法，根據方法的行為命名，只描述方法的意義，而不采用方法的目的命名。比如系統的添加新用戶，用戶可以前臺注冊，也可以治理員后臺添加，方法會被重用，所以最好不要用使用register，采用add會更好寫。避免使用與web層相關的方法。
Web層方法最好是貼近web的語言，如register，login，logout等方法。

4. 變量

變量是一方法中重要的元素，一個貼切的名稱，能讓這段代碼優雅百倍（夸張一下）。變量名首字母小寫。

變量屬于名稱，避免用采用其他詞性。

采用名稱要能代表在方法中的意義。假如員工列表：

最好是使用List employees或則employeeList而不是往使用List list或則更糟糕的List l，假如應用了List employees和Map employees可以分別使用employeeList和employeeMap。

自定義類型的變量可以采用本身的名稱，把首字母改為小寫。

5. Xml文件名

Xml命名采用與類名相似的方法，采用首字母大寫的駝峰標示。

Ibatas映射文件:namespace名稱為該模塊實體類的名稱，首字母大寫，typealias采用該類*** name。resultMap和sql名稱采用首字母小寫的命名規則，方法名稱與數據層方法名稱一致。

Form和FormItem文件名才用首字母大寫的駝峰標示。Form名稱也使用首字母大寫的格式。Form中的item名稱使用與form表單類的屬性名稱。采用駝峰標示（最好不使用_分隔）

Action文件名稱使用首字母大寫，文件package和action name字段采用所有字母小寫的格式。

6. URL命名

url路徑名稱同一采用小寫（所有字母都用小寫）,用get方法提交的參數名和url路徑名一樣使用小寫。

（1）J2EE規范

①J2EE規范

J2EE(Java 2 Platform，Enterprise Edition）是SUN公司定義的一個開發分布式企業級應用的規范。它提供了一個多層次的分布式應用模型和一系列開發技術規范。多層次分布式應用模型是指根據功能把應用邏輯分成多個層次，每個層次支持相應的服務器和組件，組件在分布式服務器的組件容器中運行（如Servlet組件在Servlet容器上運行，EJB組件在EJB容器上運行），容器間通過相關的協議進行通訊，實現組件間的相互調用。遵從這個規范的開發者將得到行業的廣泛支持，使企業級應用的開發變得簡單、快速。

②J2EE組件層次J2EE組件和層次如圖1-1所示。

圖1-1 J2EE組件層次(略)

①. J2EE規范定義了如下組件：
A. 客戶端組件
B. Web組件
C. EJB組件

②. J2EE規范定義了以下四個層次。

A. 客戶端層(Client Tier)
客戶端層用來實現企業級應用系統的操縱界面和顯示層。另外，某些客戶端程序也可實現業務邏輯。可分為基于Web的和非基于Web的客戶端兩種情況。基于Web的情況下主要作為企業Web服務器的瀏覽器。非基于Web的客戶層則是獨立的應用程序，可以完成瘦客戶機無法完成的任務。

B. Web層
為企業提供Web服務。包括企業信息發布等。Web層由Web組件組成。J2EE Web組件包括JSP頁面和Servlets。Web層也可以包括一些JavaBeans。Web層主要用來處理客戶請求，調用相應的邏輯塊，并把結果以動態網頁的形式返回到客戶端。

C. 業務層(Business Tier)
業務層也叫EJB層或應用層，它由EJB服務器和EJB組件組成。一般情況下很多開發商把Web服務器和EJB服務器產品結合在一起發布，稱為應用服務器。EJB層用來實現企業級信息系統的業務邏輯。這是企業級應用的核心，由運行在業務層中的EJB來處理。一個Bean從客戶端接收數據、處理，然后把數據送到企業信息系統層存儲起來。同樣，一個Bean也可以從企業信息系統取出數據，發送到客戶端程序。業務層中的EJB要運行在容器中，容器解決了底層的題目，如事務處理、生命周期、狀態治理、多線程安全治理、資源池等。

D. 企業信息系統層（Enterprise Information System tier)
處理企業系統軟件，包括企業基礎系統、數據庫系統及其他遺留的系統。J2EE將來的版本支持連接架構（Connector Architecture)。它是連接J2EE平臺和企業信息系統層的標準API。
業務層和Web層共同組成了三層J2EE應用的中間層，其他兩層是客戶端層和存儲層或企業信息系統層。

E. J2EE的分布應用技術
為實現企業級分布式應用，J2EE定義了豐富的技術標準，符合這些標準的開發工具和API為開發企業級應用提供支持。這些技術涵蓋數據庫訪問、分布式通訊、安全等。為分布式應用提供支持的多方面。

a. 組件技術
J2EE的核心思想是基于組件/容器的應用。每個組件提供了方法、屬性、事件的接口。組件可以由多種語言開發。組件是可以重用的、共享的、分布的。

b. Servlets和JSP
Servlets用來天生動態頁面或接收用戶請求產生相應操縱(調用EJB)。JSP基于文本。通過容器產生相應的Servlets，使內容和顯示分開。J2EE中提供了Servlet API，用于創建Servlets。

c. EJB技術
EJB規范提供了一種開發和部署服務器端組件的方法。每個EJB是按功能邏輯劃分的，開發時不必關注系統底層細節題目，只關注具體的事務分析。EJB開發完畢后，按規范部署在EJB容器，完成相應的事務功能。EJB支持分布式計算。真正體現了企業級的應用。

d. 數據庫訪問
無論是傳統的企業信息系統還是將來的企業信息系統，數據庫都占有重要的地位。開發分布式系統要求數據庫訪問具有良好的靈活性和擴展性。JDBC（JavaDatabase Connectivity)是一個獨立于特定的數據庫治理系統的開發接口。它提供一個通用的訪問SQL數據庫和存儲結構的機制，支持基本SQL功能的一個通用底層的應用程序編程接口。它在不同的數據庫界面上提供了一個同一的用戶界面。提供了多種多樣的數據庫連接方式。J2EE中提供了JDBC API使多種數據庫操縱簡單、可行。

e. 分布式通訊技術
分布式通訊技術是分布式企業系統的核心技術。J2EE框架為Web應用和EJB應用提供多種通訊模式。
為了使運行于某一機器上的對象調用另一臺機器的對象，J2EE實現了如下通訊方式：

• Java RMI(Remote Method Invoke)：遠程方法調用。Java RMI實現Java對象間的遠程通訊。服務器用注冊器把一個名字和遠程對象綁在一起，客戶機通過名字從服務器注冊器上查找遠程對象，找到后下載遠程對象的本地代理，調用遠程對象的方法。
• Java IDL（Java Inte***ce Defilation Language)：接口定義語言。可以實現Java對象的符合CORBA規范的遠程對象通訊。
• JNDI（Java Naming and Directory Inte***ce)：Java命名和目錄接口。JNDI為分布式系統訪問遠程對象提供了一個標準的命名接口。EJB主接口對象、數據源、消息服務器等都可以用JDNI樹的形式注冊到名稱服務器中，調用它們的對象通過符合JDNI的程序接口在JNDI名稱服務器中查找指定名稱的遠程對象。
• JMS（Java Message Service)：Java消息服務。為開發消息中間件應用程序定義了一套規范。Java客戶端和Java中間層訪問消息系統只要實現JMS定義的簡單的接口，就可以實現復雜的應用，而不必往關注低級的技術細節。

08 JAVA編程規范

1. 應用范圍

本規范應用于采用J2EE規范的項目中，所有項目中的JAVA代碼（含JSP，SERVLET，JAVABEAN，EJB）均應遵守這個規范。同時，也可作為其它項目的參考。

2. 設計類和方法

（1）創建具有很強內聚力的類

方法的重要性往往比類的重要性更輕易理解，方法是指執行一個同一函數的一段代碼。類常被錯誤的視為是一個僅僅用于存放方法的容器。有些開發職員甚至把這種思路作了進一步的發揮，將他們的所有方法放進單個類之中。

① J2EE是一套全然不同于傳統應用開發的技術架構，包含很多組件，主要可簡化且規范應用系統的開發與部署，進而進步可移植性、安全與再用價值。

② J2EE 的四層模型

• 運行在客戶端機器上的客戶層組件
• 運行在J2EE服務器上的Web層組件
• 運行在J2EE服務器上的業務邏輯層組件
• 運行在EIS服務器上的企業信息系統(Enterprise information system)層軟件

09 J2EE應用程序組件

J2EE應用程序是由組件構成的.J2EE組件是具有獨立功能的軟件單元，它們通過相關的類和文件組裝成J2EE應用程序，并與其他組件交互

J2EE說明書中定義了以下的J2EE組件:

• 應用客戶端程序和applets是客戶層組件.
• Java Servlet和JavaServer Pages(JSP)是web層組件.
• Enterprise JavaBeans(EJB)是業務層組件.

1. 客戶層組件
J2EE應用程序可以是基于web方式的,也可以是基于傳統方式的.

2. web 層組件
J2EE web層組件可以是JSP 頁面或Servlets.按照J2EE規范，靜態的HTML頁面和Applets不算是web層組件。正如下圖所示的客戶層那樣，web層可能包含某些 JavaBean 對象來處理用戶輸進，并把輸進發送給運行在業務層上的enterprise bean 來進行處理。

3. 業務層組件
業務層代碼的邏輯用來滿足銀行，零售，金融等特殊商務領域的需要,由運行在業務層上的enterprise bean 進行處理.下圖表明了一個enterprise bean 是如何從客戶端程序接收數據，進行處理(假如必要的話), 并發送到EIS 層儲存的，這個過程也可以逆向進行。有三種企業級的bean: 會話(session) beans, 實體(entity) beans, 和消息驅動(message-driven) beans. 會話bean 表示與客戶端程序的臨時交互.當客戶端程序執行完后, 會話bean 和相關數據就會消失. 相反, 實體bean 表示數據庫的表中一行永久的記錄. 當客戶端程序中止或服務器封閉時, 就會有潛伏的服務保證實體bean 的數據得以保存.消息驅動 bean 結合了會話bean 和 JMS的消息監聽器的特性, 答應一個業務層組件異步接收JMS 消息.

4. 企業信息系統層
企業信息系統層處理企業信息系統軟件包括企業基礎建設系統例如企業資源計劃(ERP), 大型機事務處理, 數據庫系統,和其它的遺留信息系統. 例如，J2EE 應用組件可能為了數據庫連接需要訪問企業信息系統3, J2EE平臺由一整套服務（Services）、應用程序接口（APIs）和協議構成，它對開發基于Web的多層應用提供了功能支持，下面對J2EE中的 13種技術規范進行簡單的描述

5. JDBC(Java Database Connectivity)
JDBC API為訪問不同的數據庫提供了一種同一的途徑，象ODBC一樣，JDBC對開發者屏蔽了一些細節題目，另外，JDCB對數據庫的訪問也具有平臺無關性。 JNDI(Java Name and Directory Inte***ce)
JNDI API被用于執行名字和目錄服務。它提供了一致的模型來存取和操縱企業級的資源如DNS和LDAP，本地文件系統，或應用服務器中的對象。

6. EJB(Enterprise JavaBean)
J2EE技術之所以贏得媒體廣泛重視的原因之一就是 EJB。它們提供了一個框架來開發和實施分布式商務邏輯，由此很明顯地簡化了具有可伸縮性和高度復雜的企業級應用的開發。EJB規范定義了EJB組件在何 時如何與它們的容器進行交互作用。容器負責提供公用的服務，例如目錄服務、事務治理、安全性、資源緩沖池以及容錯性。但這里值得留意的是，EJB并不是實 現J2EE的唯一途徑。正是由于J2EE的開放性，使得有的廠商能夠以一種和EJB平行的方式來達到同樣的目的。 RMI(Remote Method Invoke)

正如其名字所表示的那樣，RMI協議調用遠程對象上方法。它使用了序列化方式在客戶端和服務器端傳遞數據。 RMI是一種被EJB使用的更底層的協議。

7. Java IDL/CORBA
在Java IDL的支持下，開發職員可以將Java和CORBA集成在一起。他們可以創建Java對象并使之可在CORBA ORB中展開, 或者他們還可以創建Java類并作為和其它ORB一起展開的CORBA對象的客戶。后一種方法提供了另外一種途徑，通過它Java可以被用于將你的新的應 用和舊的系統相集成。 JSP(Java Server Pages)

JSP頁面由HTML代碼和嵌進其中的Java代碼所組成。服務器在頁面被客戶端所請求以后對這些Java代碼進行處理，然后將天生的HTML頁面返回給客戶真個瀏覽器。

8. Java Servlet
Servlet是一種小型的Java程序，它擴展了Web服務器的功能。作為一種服務器真個應用，當被請求時開始執行，這和CGI Perl腳本很相似。Servlet提供的功能大多與JSP類似，不過實現的方式不同。JSP通常是大多數HTML代碼中嵌進少量的Java代碼，而 servlets全部由Java寫成并且天生HTML。

9. XML(Extensible Markup Language)
XML是一種可以用來定義其它標記語言的語言。它被用來在不同的商務過程中共享數據。

XML的發展和Java是相互獨立的，但是，它和Java具有的相同目標正是平立性。通過將Java和XML的組合，您可以得到一個完美的具有平立性的解決方案。

10. JMS(Java Message Service)
MS是用于和面向消息的中間件相互通訊的應用程序接口(API)。它既支持點對點的域，有支持發布/訂閱 (publish/subscribe)類型的域，并且提供對下列類型的支持：經認可的消息傳遞,事務型消息的傳遞，一致性消息和具有持久性的訂閱者支 持。JMS還提供了另一種方式來對您的應用與舊的后臺系統相集成。

11. JTA(Java Transaction Architecture)
JTA定義了一種標準的API，應用系統由此可以訪問各種事務監控。

12. JTS(Java Transaction Service):
JTS是CORBA OTS事務監控的基本的實現。JTS規定了事務治理器的實現方式。該事務治理器是在高層支持Java Transaction API (JTA)規范，并且在較底層實現OMG OTS specification的Java映像。JTS事務治理器為應用服務器、資源治理器、獨立的應用以及通訊資源治理器提供了事務服務。

13. JavaMail
JavaMail是用于存取郵件服務器的API，它提供了一套郵件服務器的抽象類。不僅支持SMTP服務器，也支持IMAP服務器。

14. JAF(JavaBeans Activation Framework)
JavaMail利用JAF來處理MIME編碼的郵件附件。MIME的字節流可以被轉換成Java對象，或者轉換自 Java對象。大多數應用都可以不需要直接使用JAF。

以上就是本文的全部內容，希望對大家的學習有所幫助，也希望大家多多支持億速云。