Java編碼規(guī)范2014526

1、Java 編碼規(guī)范1. 概述本標(biāo)準(zhǔn)系公司首次發(fā)布實(shí)施，主要針對公司所有軟件產(chǎn)品源代碼范圍的Java編碼風(fēng)格，對Java文件的文件組織、代碼風(fēng)格、注釋、命名、聲明、異常、習(xí)慣等方面均做規(guī)范，以保障公司項(xiàng)目代碼的易維護(hù)性和編碼安全性。1.1. 術(shù)語l Pascal case - 所有單詞第一個(gè)字母大寫，其它字母小寫。例如：Person, OrderDetail,OilTank。l Camel case - 除了第一個(gè)單詞，所有單詞第一個(gè)字母大寫，其他字母小寫。例如：oilLevel, customerName。在后面的描述中我們使用 Pascal 代表第一種表示方式， Camel代表第二種表示方式

2、。2. 重要規(guī)范2.1. 操作規(guī)范2.1.1. 模板及格式化 開發(fā)人員必須保證代碼格式化的一致性，否則可能會(huì)導(dǎo)致代碼沖突。輕微的沖突耗費(fèi)人力合并代碼；嚴(yán)重時(shí)可能導(dǎo)致代碼丟失，引起bug或者故障。 開發(fā)人員必須配置cdrundle的codetemplates.xml代碼模板文件。 開發(fā)人員必須配置cdrundle的cdrundleFormatter.xml代碼格式化文件。 每次提交代碼之前，必須對java代碼format。 模板文件：Eclipse中配置的位置： Window-Preferences-Java-Code templates Window-Preferences-Java-Form

3、atter2.1.2. 代碼提交 為防止沖突，任何時(shí)候，代碼（及配置文件）提交前，先從SVN中更新代碼和配置文件，以及早發(fā)現(xiàn)不兼容的代碼變更和沖突。提交代碼（及配置文件）時(shí)，如果發(fā)生沖突時(shí)，先看歷史說明，再找相關(guān)人員確認(rèn)，堅(jiān)決不允許強(qiáng)制覆蓋。每次提交代碼之前，必須檢查是否有eclipse warning，并修復(fù)所有的warning。開發(fā)過程中定期使用FindBugs掃描代碼，合并代碼時(shí)不允許出現(xiàn)高等級(jí)問題。2.1.3. 垃圾清理 對從來沒有用到的或者被注釋的方法、變量、類、配置文件，動(dòng)態(tài)配置屬性等要堅(jiān)決從系統(tǒng)中清理出去，避免造成過多垃圾。2.2. 日志規(guī)范2.2.1. 日志輸出 l 生產(chǎn)代碼禁

4、止以System及Throwable.printStackTrace的方式輸出日志信息，必須用Logger替代。l 對trace/debug/info級(jí)別的日志輸出，必須使用條件輸出形式，否則大量的日志會(huì)增加來自對象toString的性能成本。l 對于日志的打印，任何情況下都不允許日志錯(cuò)誤導(dǎo)致業(yè)務(wù)失敗。2.2.2. 錯(cuò)誤日志 對于由于系統(tǒng)原因造成業(yè)務(wù)處理失敗的事件，需要記錄錯(cuò)誤日志。非系統(tǒng)原因的業(yè)務(wù)處理失敗，不應(yīng)該記錄錯(cuò)誤日志（推薦使用warn級(jí)別），避免錯(cuò)誤日志過大，影響緊急情況下的故障分析不診斷。2.3. 注釋規(guī)范l 對于一個(gè)完整的類，應(yīng)該包括Cdrundle的版權(quán)注釋、類的說明注釋、類成

5、員變量注釋，以及public、protected、private方法的注釋（setter、getter、接口的實(shí)現(xiàn)方法除外）。l 必須保證代碼和注釋的一致性。l 正確區(qū)分使用文檔注釋和實(shí)現(xiàn)邏輯注釋。2.4. 異常處理l 捕捉到的異常，不允許不做任何處理就截?cái)?，至少要記入日志，或重新拋出。l 最外層的業(yè)務(wù)使用者，必須處理異常，將其轉(zhuǎn)化為用戶可以理解的內(nèi)容。2.5. 安全規(guī)范2.5.1. WEB安全 l 對于前臺(tái)的web頁面，必須加上表單防重復(fù)提交功能；對于業(yè)務(wù)關(guān)鍵字段需要加上防篡改的功能，否則可能造成業(yè)務(wù)重復(fù)執(zhí)行或者被客戶端惡意修改。l 對于前臺(tái)的web頁面，嚴(yán)禁出現(xiàn)方便調(diào)試的后門頁面。l 不允

6、許出現(xiàn)頁面向自身重定向、或者多個(gè)頁面間相互重定向的情況。如果控制不當(dāng)，很容易造成系統(tǒng)宕機(jī)。2.5.2. 敏感信息的保護(hù)用戶的敏感信息包括密碼、短信驗(yàn)證碼、支付驗(yàn)證碼、身份證號(hào)、銀行卡號(hào)、銀行密鑰，商戶密鑰等信息，用戶敏感信息不能泄露，否則可能會(huì)帶來不安全因素?？赡軙?huì)導(dǎo)致敏感信息泄露的方式有：Logger、URL的get參數(shù)（因?yàn)閁RL的get參數(shù)會(huì)在apache日志中被輸出）。2.6. 通用規(guī)范2.6.1. 配置信息的使用 避免將UserID、URL、文件名、系統(tǒng)開關(guān)參數(shù)、業(yè)務(wù)規(guī)則的可變參數(shù)等硬編碼。 2.6.2. 資源的使用對系統(tǒng)資源的訪問，使用后必須釋放系統(tǒng)資源。這類資源包括：文件流、線程

7、、網(wǎng)絡(luò)連接、數(shù)據(jù)庫連接等。 l 對于文件、流的IO操作，必須通過finally關(guān)閉。 l 對于線程，線程資源必須通過線程池提供，不允許在應(yīng)用中自行顯式創(chuàng)建線程。 l 對于網(wǎng)絡(luò)連接與數(shù)據(jù)庫連接，必須由框架通過連接池提供，不允許應(yīng)用中自行建立網(wǎng)絡(luò)與數(shù)據(jù)庫連接。3. 類的編寫規(guī)范l 所有包、類、接口、方法、屬性、變量、參數(shù)均使用英文單詞進(jìn)行命名。l 命名包、類、接口、方法以及變量時(shí)，盡量使用貼近問題域的且意義豐富的名稱。l 修改源代碼時(shí)，應(yīng)盡量保持與所修改系統(tǒng)的編碼風(fēng)格保持一致。l 所有包名必須使用pany前綴，所有項(xiàng)目使用ject name，compan

8、y 是公司簡稱，project name 是項(xiàng)目的縮寫。l 注意盡量不要用生僻的縮寫，尤其是中文縮寫。4. 格式規(guī)范l 包的導(dǎo)入應(yīng)該按照相關(guān)性進(jìn)行分組。import java.io.IOException;import .URL;import java.rmi.RmiServer;import java.rmi.server.Server;import javax.swing.JPanel;import javax.swing.event.ActionEvent;import org.linux.apache.server.SoapServer;l 只倒入明確需要的類，這樣只要看導(dǎo)入列表，就可

9、以知道該類依賴于哪些類和接口，保證可讀性。import java.util.List; / 避免: import java.util.*import java.util.Arraylist;import java.util.HashSet;l 類和接口中元素的布局順序。1、類和接口的文檔描述2、類和接口的聲明3、類的靜態(tài)變量，按照public，protected，package，private的順序。4、實(shí)例變量，按照public，protected，package，private的順序。5、類的方法，無固定順序。l 類的聲明，基類和實(shí)現(xiàn)的接口應(yīng)該獨(dú)立成行，保證可讀性。class UserMa

10、nagerImplextends AbstractManagerimplements IUserManagerl 方法修飾關(guān)鍵字定義順序。 static abstract synchronized unuaual final native methodName注意訪問標(biāo)示符一定要在最前面。public static double square(double a);/避免: static public double square(double a);l 變量聲明，采用 Camel 表示法不要在一行聲明多個(gè)變量。/推薦int level;int size;/避免int level, size;l

11、保證明確的類型轉(zhuǎn)換，不要默認(rèn)進(jìn)行隱式類型轉(zhuǎn)換intValue = (int) floadValue; /避免 intValue = floatValuel 數(shù)組指示符緊跟類型變量int a = new int20; / 避免: int a = new int20一個(gè)變量要代表獨(dú)立的意思，不要在其生命周期賦予它不同的概念。int tempValue;tempValue = maxValue;tempValue = minValue;tempValue = anotherValue;tempValue 在生命周期內(nèi)表示了各種各樣的意圖，增加理解代碼的難度。 應(yīng)該為每個(gè)獨(dú)立概念定義單獨(dú)的變量：int

12、 tempMaxValue;int tempMinValue;int tempAnotherValue;l 僅僅循環(huán)控制變量才能出現(xiàn)在 for()循環(huán)中sum = 0;for (i = 0; i 100; i+) sum += valuei;/避免:for (i = 0, sum = 0; i 100; i+)sum += valuei;l 循環(huán)變量應(yīng)靠近循環(huán)體初始化 isDone = false while(!isDone)/避免isDone = false;while(!isDone)l 避免長的布爾表達(dá)式，應(yīng)換成多個(gè)更容易理解的表達(dá)式。bool isFinished = (element

13、No maxElement);bool isRepeatedEntry = elementNo = lastElement;if (isFinished | isRepeatedEntry) / 避免if (elementNo maxElement)| elementNo = lastElement) l 不要在條件語句中執(zhí)行方法，以提高可讀性InputStream stream = File.open(fileName, w);if (stream != null) /避免if (File.open(fileName, w) != null) l 代碼縮進(jìn)，應(yīng)該使用 4 個(gè)空格為一個(gè)單位進(jìn)行

14、縮進(jìn)。public String invoke() throws Exception .String profileKey = invoke: ;try .UtilTimerStack.push(profileKey);if (executed) .test = true;catchl 條件語句的主要形式，即使單條語句，也要使用括號(hào)括起來。if (condition) statements;if (condition) statements; else statements;if (condition) statements; else if (condition) statements; e

15、lse statements;l 空循環(huán)體也要使用完整的塊for (initialization; condition; update) ;l switch 語句的使用格式switch (condition) case ABC :statements;/穿透，一定要做出注釋case DEF :statements;break;case XYZ : statements; break;default : statements; break;l try-catch 使用格式try statements;catch (Exception exception) statements;try state

16、ments;catch (Exception exception) statements;finally statements;l 空格的使用1、運(yùn)算符兩邊應(yīng)該各有一個(gè)空格。2、Java 保留字后面應(yīng)跟隨一個(gè)空格。3、逗號(hào)后面應(yīng)跟隨一個(gè)空格。4、冒號(hào)兩個(gè)應(yīng)各有一個(gè)空格。5、分號(hào)后面應(yīng)跟隨一個(gè)空格。a = (b + c) * d;/ NOT: a=(b+c)*dwhile (true) / NOT: while(true). doSomething(a, b, c, d);/ NOT: doSomething(a,b,c,d); case 100 :/ NOT: case 100:for (i

17、= 0; i 10; i+) / NOT: for(i=0;i10;i+) .l 邏輯上緊密相關(guān)的代碼塊應(yīng)該用一個(gè)空行分開。/ Create a new identity matrixMatrix4x4 matrix = new Matrix4x4();/ Precompute angles for efficiencydouble cosAngle = Math.cos(angle); double sinAngle = Math.sin(angle);/Specify matrix as a rotation transformationmatrix.setElement(1, 1, co

18、sAngle); matrix.setElement(1, 2, sinAngle); matrix.setElement(2, 1, -sinAngle); matrix.setElement(2, 2, cosAngle);/ Apply rotationtransformation.multiply(matrix);l 為了保證可讀性，變量名應(yīng)該左對齊。TextFilefile;int nPoints;doublex, y;/避免TextFilefile;int nPoints;double x, y;l 像前面一般規(guī)則里說的那樣，任何提高代碼可讀性的排版都可以去嘗試， 下面是一些例子。

19、if(a = lowValue)compueSomething();else if(a = mediumValue)computeSomethingElse();else if(a = highValue)computeSomethingElseYet();value =(potential* oilDensity)/ constant1 +(depth* waterDensity) / constant2 +(zCoordinateValue * gasDensity)/ constant3;minPosition =computeDistance(min, x, y, z);average

20、Position =computeDistance(average, x, y, z);switch (phase) casePHASE_OIL : text= Oil;break;casePHASE_WATER :text= Water;break;casePHASE_GAS :text= Gas;break;l 當(dāng)對 if 語句中的條件進(jìn)行折行時(shí)，應(yīng)該使折行的條件語句相對主功能語句再行縮進(jìn) 4 個(gè)空格，以突出主要功能語句。/使用這種縮進(jìn)，突出主要功能語句。if (condition1 & condition2)| (condition3 & condition4)|!(condition5

21、 & condition6) doSomethingAboutIt();/避免使用這種縮進(jìn)，主功能語句不突出。 if (condition1 & condition2)| (condition3 & condition4)|!(condition5 & condition6) doSomethingAboutIt();l 三元條件運(yùn)算符 可以使用如下三種表達(dá)方式，條件要用括號(hào)括起來。alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta: gamma;alpha = (aLo

22、ngBooleanExpression)? beta: gamma5. 命名規(guī)范5.1. 一般命名規(guī)范l 包名應(yīng)該用小寫字母，不要出現(xiàn)下劃線等符號(hào)，名詞用有意義的縮寫或 者英文單詞。示例：/推薦 com.cdrundle.normativefile.daojava.lang.util/避免com.Esse-tech.buSinessl 所有類命名使用 Pascal 表示方式，使用名詞組合。UserManager, ClassLoader, HttpHeaderResultl 接口命名使用字母“I”加上 Pascal 形式的表示方式。IQuery, IDataAccess,IReportBuil

23、derl 使用名詞組合或形容詞去命名一個(gè)接口，接口聲明了一個(gè)對象能提供的 服務(wù)，也描述了一個(gè)對象的能力。一般以“able”和“ible”作為后綴， 代表了一種能力。public interface Runnablepublic void run();public interface Accessiblepublic Context getContext();l 變量名和參數(shù)名使用 Camel 表示方式。userName, objectFactory, entrys, listl 對于常量名，使用大寫字母，并使用下劃線做間隔。 MAX_TIMES, DEFAULT_NAME 程序中應(yīng)該使用常量代

24、替“25”，“100”等實(shí)際的數(shù)字，如：/推薦if(times = MAX_TIMES)/避免if(times = 25)這樣做的好處是，當(dāng)因需要修改實(shí)際的數(shù)字時(shí)，比如修改 25 為 30，只需要 修改一處。l 方法名應(yīng)該使用動(dòng)詞開頭，使用Camel表示方式,一般由動(dòng)詞+名詞組成。getName, initialize, addParameter, deleteUserl 縮寫字母也應(yīng)該保持首字母大寫exportHtmlSource(); / 避免: exportHTMLSource();openDvdPlayer();/ 避免: openDVDPlayer();l 變量的名字應(yīng)該和類型名稱一

25、致void setTopic(Topic topic) / 避免: void setTopic(Topic value)/ 避免: void setTopic(Topic aTopic)/ 避免: void setTopic(Topic t)void connect(Database database)/ 避免: void connect(Database db)/ 避免: void connect(Database oracleDB)當(dāng)同時(shí)定義多個(gè)屬于同一個(gè)類的變量時(shí)，把類型作為實(shí)例的后綴，如：Point startPoint; Point centerPoint;這樣做是為了從實(shí)例名就可以

26、推斷它的類型名稱。l 根據(jù)變量的作用范圍，作用范圍大的應(yīng)該使用長名稱，作用范圍大，表明變量的生命周期比較長，為了有助于理解，應(yīng)盡量用長名稱以表達(dá)變量的真實(shí)意圖。反之，對于作用范圍小，可以使用一些簡化的名稱，比如 i，j，k 等，提高編程效率。for(int i =0;i times; i+)5.2. 特殊命名規(guī)范l 使用 get/set 對類屬性進(jìn)行訪問，這是 Java 社區(qū)的核心編碼規(guī)范。l 使用 is 前綴表示一個(gè)布爾變量和方法。isUsed, isEmpty,isVisible,isFinished有時(shí)也可以使用 has，can，should：boolean hasLicense();b

27、oolean canEvaluate();boolean shouldAbort = false;l 在查詢方法中應(yīng)使用 find 作為前綴vertex.findNearestVertex();matrix.findSmallestElement();node.findShortestPath(Node destinationNode);l 使用 initialize 作為對象初始化的方法前綴，也可以簡寫為init initializeFiles();init();initFontSet();l 對于對象集合，變量名稱應(yīng)使用復(fù)數(shù)。Collection points;intvalues;l 對于

28、抽象類，應(yīng)該使用Abstract前綴。AbstractReportBuilder，AbstractBeanFactoryl 對于表示編號(hào)的變量，應(yīng)加 No 后綴。tableNo, userNo,employeeNol 常在一起使用的對稱詞匯，這些詞匯一起使用，方法的表達(dá)意圖自然可 以互相推測和演繹。get/set, add/remove,create/destroy,start/stop, insert/delete, increment/decrement, begin/end, first/last, up/down, min/max,next/previous,old/new, open

29、/close, show/hide, suspend/resumel 避免使用否定布爾變量bool isError; / 避免: isNoErrorbool isFound; / 避免: isNotFoundl 異常類應(yīng)該使用 Exception 作為后綴。AccessException, RuntimeExceptionl 缺省接口實(shí)現(xiàn)應(yīng)該使用 Default 前綴class DefaultTableCellRenderer implements TableCellRenderer l 對于單例類（Singleton），應(yīng)該使用 getInstance 方法得到單例。class UnitMa

30、nager private final static UnitManager instance = new UnitManager();private UnitManager() .public static UnitManager getInstance()return instance;l 對于工廠類，進(jìn)行創(chuàng)建對象的方法，應(yīng)該使用 new 前綴class PointFactory public Point newPoint(.) .6. 注釋規(guī)范6.1. 概述代碼中為什么要包含注釋？1、別人要調(diào)用你的程序中的公共接口，對這部分進(jìn)行文檔描述，使別人能 夠正確而有效的使用它。2、除了自己，別人

31、要閱讀和維護(hù)你的代碼。為了使代碼更容易維護(hù)，首先 要使代碼更易于理解，才能在理解的基礎(chǔ)上進(jìn)行維護(hù)。對這些代碼進(jìn)行 文檔描述，將使這個(gè)過程變得更加容易。對代碼進(jìn)行注釋，是在代碼可讀性的基礎(chǔ)上，使用自然語言對代碼所表達(dá)的意思進(jìn)行闡述。并不是說代碼可以寫的很爛，注釋寫的很詳細(xì)，這不是 好的方式。如果代碼可讀性很好，命名表意豐富，清晰，一般不需要特別多 的注釋。對于類，主要著重要描述它的職責(zé)，即它能干什么，對于復(fù)雜的算 法實(shí)現(xiàn)，應(yīng)該使用內(nèi)部實(shí)現(xiàn)注釋，說明算法的主要思路，對于長方法，要讓 閱讀代碼的人比較容易的明白方法實(shí)現(xiàn)的主要流程。反之，對于一看就懂的方法，則不需要進(jìn)行注釋，比如 get/set 方法

32、。6.2. 一般原則1、代碼應(yīng)該和注釋保持同步，如果代碼和注釋不同步，則閱讀代碼的人會(huì) 想，“到底是代碼準(zhǔn)確，還是注釋準(zhǔn)確啊”，換誰都會(huì)糊涂。2、注釋盡量簡潔，尺度沒有準(zhǔn)確的定義，大部分人能明白即可，可以將自 己的代碼給同事看看。太簡單的方法就不要注釋了，比如上面提到的get/set 方法。6.3. 注釋內(nèi)容/* Copyright (c) 2002-2006 by OpenSymphony 1* All rights reserved.*/package com.opensymphony.xwork2;import erceptor.Pr

33、eResultListener;import com.opensymphony.xwork2.util.ValueStack;import java.io.Serializable;/* 類職責(zé)簡要描述2*。* author Jason Carreira* see com.opensymphony.xwork2.ActionProxy*/public class ActionInvocation implements Serializable /* 方法簡要描述* 3* 方法詳細(xì)描述* 。* JavaDoc tags,比如* author* version 4* see 。* return a

34、 Result instance*/Result getResult() throws Exception/內(nèi)部實(shí)現(xiàn)注釋/多行內(nèi)部實(shí)現(xiàn)注釋 String name = this.getName();/* Get the Action associated with this ActionInvocation*/Object getAction();/* return whether this ActionInvocation has executed before.*executed.*/boolean isExecuted();/* Invokes the next step in proc

35、essing this ActionInvocation.* one. If Interceptors choose not to* they will call invoke() to allow the next Interceptor to execute* the Action is executed. If the ActionProxy getExecuteResult*/String invoke() throws Exception;代碼的版權(quán)信息。類描述信息，描述類的主要職責(zé)和用處。方法描述信息，描述方法是做什么的，如何調(diào)用，最好給出調(diào)用代碼示例。JavaDoc tags ,

36、用來生成 Html 形式的 API 文檔內(nèi)部實(shí)現(xiàn)注釋，用于描述復(fù)雜的算法，長方法，從為什么要這么做角度去 描述l 盡可能在類描述中加入代碼調(diào)用示例，使用標(biāo)記，提示JavaDoc 工具不要改變格式./* DateFormat is an abstract class for date/time formatting* formats and parses dates or time in a language-independent manner.* *myString = DateFormat.getDateInstance().format(myDate);* * *DateFormat df = DateFormat.getDateInstance();*for (int i = 0; i myDate.length; +i) *output.println(df.format(myDatei) + ; );* * seeFormat* seejava.util.TimeZone* version1.