程序編碼規范java

程序編碼規范

VI.0

編寫：XXX

審核：XXX

XXXX年XX月修改

目錄

一、引言.............................................................

二、命名規范.........................................................

2.1包(Package)的命名..........................................

2.3Class變量的命名.............................................

2.4接口的命名...................................................

2.5參數的命名....................................................

2.6數組的命名....................................................

2.6方法的參數....................................................

二注釋規范..........................................................

3.1塊注釋(BlockComments).......................................

3.2單行注釋(Single-LineComments)...............................

3.3尾端注釋(TrailingComments)..................................

3.4行末注釋(End-Of-LineComments)...............................

四Java文件樣式.....................................................

4.1版權信息......................................................

4.2Package/Imports...............................................

4.3Class.........................................................

4.4ClassFields..................................................

4.5存取方法二二.................................................

4.6構造函數......................................................

4.7main方法....................................................

4.8換行(WrappingLincs).........................................

4.9行長度(LineLength)...........................................

4.10語句(Statements)............................................

五排版格式..........................................................

六JSP編碼規范......................................................

七、文件與目錄.......................................................

八、日志規范.........................................................

九、設計及技巧建議...................................................

9.1表現層........................................................

9.2業務層........................................................

9.3持久層........................................................

一、引言

編碼規范對于程序員而言尤為重要，有以下兒個原因：

1、一個軟件的生命周期中，80%的花費在于維護。

2、幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發人員來維護。

3、編碼規范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼。

4、如果你將源碼作為產品發布，就需要確任它是否被很好的打包并且清晰無誤，一如已構建的其

它任何產品

為了執行規范，每個軟件開發人員必須一致遵守編碼規范中的代碼規范，代碼規范提高軟件代碼的可

讀性，使得開發人員快速和徹底的理解新代碼好的代碼風格不僅會提高可讀性，而且會使代卷?更健壯，更

為重要的是在修改時不容易出錯。現代軟件開發中，維護工作會占用80%的時間，而且開發者和維護者通常

不是同一個程序員。這意味著程序員經常要閱讀和修改別人開發的程序，別人也同樣可能需要閱讀和修改你

尸發的程序，所以制定一套完善的編碼規范非常重要。

定義本規范的目的是使項目中所有的文檔及程序編碼在寫作風格上具有?致性，增加可讀性，減少項

目組中因為換人帶來的損失，從而使程序具有良好的可讀性。

二、命名規范

2.1包(Package)的命名

包(Packages)：一個唯一包名的前綴應全部為小寫的ASCII字母，并且是一個頂級域名，通常為com、

edu、gov、mil、net、org等。包名的后續部分可根據各個不同機構內部的命名規范來定義，這類命名規范可

以由特定的目錄名來區分部門(department)、項目(project)、機器(machine)和注冊名(loginnames)0

?核心程序部分：com.xxxxxx.base

?系統管理部分：com.xxxxxx.sys

?應用維護部分：com.xxxxxx.appconfig

?項目計劃管理部分：com.xxxxxx.itcmplan

?采購管理部分：com.xxxxxx.purchase

?財務管理部分：com.xxxxxx.finance

?監測評價部分：com.xxxxxx.analyse

如果在開發過程中還有其他情況沒有涵蓋到，可以按照上述規則進行擴展。

2.2Class的命名

Class的名字必須由一個大寫字母開頭其他字母為小寫的單詞構成。類名要用完整的單詞，避免使用縮

寫詞(除非該縮寫詞被更廣泛使用，像URL,HTML)0

ActionForm類的命名：以有意義的拼音縮寫開頭后加ActionForm

Action類的命名；以有意義的拼音縮寫開頭后加Action

2.3Class變量的命名

變量名應選用易于記憶、簡短富于描述并能夠指出其用途的單詞。單詞不應以下劃線或美元符號開頭,

除一次性臨時變量外盡量避免單個字符的變量名。除了變量名外，所有實例，包括類、類常量均采用大小寫

混合的方式，第一個單詞的首字母小寫，其后單詞的首字母大寫。

charc（c,d.e常用于表示字符型）

intI（i、j、k、m、n常用于表示整型）

floatmyWidth;

實例變量（InstanceVariables）

大小寫規則和變量名相似，但前面需要一個下劃線int_employeeld;

Siring_name;

Customer—Customer;

常量（Constants）類常量和ANSI常量的聲明，應該全部大寫，單詞間用下劃線隔開。（盡量避免ANSI

常量,容易引起錯誤）staticfinalintMIN_WIDTH=4;

staticfinalintMAX_WIDTH=999;

staticfinalintGET_THE_CPU=I;

除了以下幾個特例之外，命名時應始終采用完整的英文描述符。此外，一般應采用小寫字母，但類名、

接口名以及任何非初始單詞的第一個字母要大寫。

1、盡量使用完整的英文描述符

2、采用適用于相關領域的術語

3、采用大小寫混合使名字可讀

4、盡量少用縮寫，但如果用了，要明智地使用，旦在整個工程中統一

5、避免使用長的名字（小于15個字母是個好主意）

6、避免使用類似的名字，或者僅僅是大小寫不同的名字

7、避免使用下劃線（除表態常量等）

2.4接口的命名

竹寫規則與類名相似，如interfaceRastcrDclcgatc；interfaceStoring；

方法（Mclhods）：方法名是一個動詞，采用大小寫混合的方式，第一個單詞的苜字母小寫，其后單詞的

首字母大寫,例如:

run();

runFast();

ge(Background();

2.5參數的命名

參數的命名必須與變量的命名規范一致。

2.6數組的命名

數組應該用下面的方式來命名：

byte口buffer:

而不是：

bytebuffer[];

2.6方法的參數

使用有意義的參數來命名，名字盡量和將要賦值的字段一致。例如:

SetCounter(intsize){

this.size=size;

三注釋規范

,般情況下程序有兩類注釋：實現注釋(implementationcomments)和文檔注釋(document

comments)o實現注釋是那些在C++中見過的，使用/*...*/和〃界定的注釋。文檔注釋(稱為“doc

comments")是Java獨有的，并由/**...*/界定。文檔注釋可以通過javadoc工具轉換成HTML文件。

實現注釋用來注釋代碼或者實現細節。文檔注釋從實現自由(implcmcntation-frco)的角度描述代

碼的規范。它可以使手頭沒有源碼的開發人員讀懂程序。注釋是用來對代碼進行的，并提供代碼自身沒

有提供的附加信息。注釋要包含有助于閱讀和理解程序的相關信息。例如，相應的包如何被建立或位于

哪個目錄下之類的信息不應包括在注釋中。

程序可以有4種實現注釋的風格:塊(block)、單行(singleTine)、尾端(trailing)和行末

(end-of-line)?

3.1塊注釋(BlockComments)

塊注釋通常是對文件、方法、數據結構和算法等提供描述，應置于每個文件的開始處或每個方法之前。

塊注釋也可以用于其他地方，如方法的內部。在功能和方法內部的塊注釋應該和它所描述的代碼具有?樣的

縮進格式。

塊注釋之首應該有一個空行，用于把塊注釋和代碼分割開來，比如：

/*

*在這里寫塊注釋

3.2單行注釋(Single?LineComments)

單行注釋之前也應該有一個空行.若為可以顯示在一行內短注釋，要與其后的代碼具有一樣的縮進層

級。如果一個注釋不能在一行內寫完，就該采用塊注釋(參見“塊注釋”)的方式。以下是一個Java代碼中單行

注釋的例子：

if(condition){

/*判斷條件*/

3.3尾端注釋(TrailingComments)

極短的注釋可以與它們所要描述的代碼位于同一行，但是應該有足夠的空白將代碼和注釋分開。若有

多個短注釋出現在大段代碼中，它們應該具有相同的縮進。

以下是一個Java代碼中尾端注釋的例子：

if(a==2){

returnTRUE;/*specialcase*/

}else{

returnisPrime(a);/*worksonlyforodda*/

1

3.4行末注釋(End?Of?LineComments)

利用注釋界定符“〃"，可以注釋掉整行或者一行中的一部分。它一?般不用于連續多行的注釋文本中，常

用來注釋掉連續多行的代碼段。以下是所有三種風格的例子：

if(foo>1){

/7Doadouble-flip.

I

else{

returnfalse;//Explainwhyhere.

；/if(bar>I){

；/

////Doatriple-flip.

；/...

八

//else{

/7returnfalse;

//}

Java文件樣式

所有的Java(\ava)文件都必須遵守如下的樣式規則

4.1版權信息

版權信息必須在java文件的開頭，比如;

/**版權所有？****年-****年XXXXX科技有限公司，

*保留所有權利。

*/

其他不需要出現在javadoc的信息也可以包含在這里。

4.2Package/lmports

package行要在import行之前，impori中標準的包名要在本地的包名之前，而且按照字母順序排列。

如果import行中包含了同一個包中的不同子目錄，則應該用*來處理。

packagecom.aoch.ecity........;

importjava.io.*;

這里java.io.*使用來代替InpinStrcamandOuipuiSlrcam的。

4.3Class

類的注釋一般是用來解釋類功能的，需要按照如下格式編寫：

*Vp>類名:Jpc</p>

*<p>描述:Jpc服務的用戶接口類，調用了JpcScrvicc類的實現。

*</p>

*<p>版權聲明：Copyright(c)2003-2004,

www.公司網址">XXXX科技有限公司v/a></p>

*

*?author<ahref="作者郵箱”>作者姓名</a>

*@version1.5.6

*/

4.4ClassFields

類的成員變量必須通過注釋說明其含義，不管成員變量是publicxprotected還是private的都要說明。

4.5存取方法

若類的存取方法只是用于對類的變量賦值、取值的話，在類的成員變量有注釋的情況下，類變量的存

取方法可以沒有注釋。

/**

*功能說明：…

市@paramopcDaia要設置的Opc數據

*@returntrue成功false失敗

*@throwsServiceUnavailableException服務不可用異常

*/

publicstaticbooleansctDataToOpc(OpcDataopcData)throwsServiceUnavailableException{

returntrue;

)

pubIicint[]getPackets(Strings){returncopyArray(packets,offset);)

pubIicint[]getDytes(){returncopyArray(bytes,offset);}

pubIicint[]getPackets(){returnpackets;}

pubIicvoidsetPackets(int[]packets){this.packets=packets;}

4.6構造函數

構造函數，要用遞增的方式書寫(參數多的寫在后面)，這樣可以使方法和參數更易讀。

4.7main方法

如果已經定義了main(Slrirg[])方法，那么它就應該寫在類的底部。

4.8換行(WrappingLines)

當一個表達式無法容納在一行內時，可以依據如下一般規則斷開：

?在一個逗號后面斷開

?在一個操作符前面斷開

?寧可選擇較高級別(higher-level)的斷開，而非較低級別(lower/evel)的斷開

?新的一行應該與上一行同一級別表達式的開頭處對齊-如果以上規則導致你的代碼混亂或者使

代碼都推擠在右邊,那就代之以縮進8個空格.

以下是斷開方法調用的一些例子：

someMcthod(longExpressionl,longExpression2,longExpression3.

IongExprcssion4,longExprcssion5);

var=someMethodl(longExpression1,

sonieMethod2(longExpression2,

longExpression3));

以下是兩個斷開算術表達式的例子。前者更好，因為斷開處位于括號表達式的外邊，這是個較高級別

的斷開。

longName1=longName2*(longName3+longName4-longName5)

+4*longname6;Z/PREFFER

longName1=longName2*(longName3+longName4

-longName5)+4*Iongname6;//AVOID

以下是兩個縮進方法聲明的例子。前者是常規情形。后者若使用常規的縮進方式將會使第二行和第三

行移得很靠右，所以代之以縮進8個空格

/'/CONVENTIONALINDENTATION

somcMcthod(intanArg,ObjectanothcrArg.StringyctAnothcrArg,

ObjectandStillAnother)(

}

//INDENT8SPACESTOAVOIDVERYDEEPINDENTS

privatestaticsynchronizedhorkingLongMethodName(intanArg,

ObjectanothcrArg,StringyetAnotherArg,

ObjectandStill/\nother){

I

if語句的換行通常使用8個空格的規則，因為常規縮進(4個空格)會使語句體看起來比較費勁。比如：

//DON'TUSETHISINDENTATION

if((conditionl&&condition?)

||(condition?&&condition4)

||!(condition5&&condition6)){//BADWRAPS

doSomethingAboutltO;//MAKETHISLINEEASYTOMISS

；/USETHISINDENTATIONINSTEAD

if((condition1&&condition?)

||(conditions&&condition4)

||!(condition5&&condition6)){

doSoniethingAboutIt();

I

；/ORUSETHIS

if((condition1&&condition2)||(conditions&&condition4)

||!(conditions&&condition6)){

doSomethingAboutIt();

這里有三種可行的方法用于處理三元運黨表達式：

alpha=(aLongBooleanExpression)?beta:gamma;

alpha=(aLongBooleanExpression)?beta

:gamma;

alpha=(aLongBooleanExpression)

?beta

:gamma;

4.9行長度(LineLength)

盡量避免一行的長度超過80個字符，因為很多終端和工具不能很好處理之。

注意：用于文檔中的例子應該使用更短的行長，長度一般不超過70個字符。

4.10語句(Statements)

?簡單語句(SimpleStatements)

每行至多包含一條語句，例如:

argv++;//Correct

argc—;//Correct

argv++;argc—;//AVOID!

?復合語句(CompoundStatements)

復合語句是包含在大括號中的語句序列，形如“{語句}"，例如下面各段：

-被括其中的語句應該較之復合語句縮進一個層次

-左大括號”{“應位于復合語句起始行的行尾；右大括號“}"應另起一行并與復合語句首行對齊。

-大括號可以被用于所有語句，包括單個語句，只要這些語句是諸如if-else或for控制結構的一部

分。這樣便于添加語句而無需擔心由于忘了加括號而引入bUgo

?返回語句(retumStatements)

一個帶返回值的return語句不使用小括號"()"，除非它們以某種方式使返回值更為顯見。例如：

return;

returnmyDisk.size();

return(size?size:defaultSize);

?if>if-else,ifelse-ifelse語句(if,if-else,ifelse?ifelseStatements)

if-clsc語句應該具有如卜.格式：

if(condition){

statements;

if(condition){

statements;

}else{

statements;

I

if(condition){

statements;

}elseif(condition){

statements;

}else{

statements;

)

注意：if語句總是用“{”和1”括起來，避免使用如下容易引起錯誤的格式:

if(condition)//AVOID!THISOMITSTHEBRACES{}!

statement;

?for語句(forStatements)

一個for語句應該具有如下格式：

!or(initialization;condition;update){

statements;

一個空的for語句(所有工作都在初始化，條件判斷，更新子句中完成)應該具有如下格式:

for(initialization;condition;update);

當在for語句的初始化或更新子句中使用逗號時，避免因使用三個以上變量，而導致復雜度提高。若需

要，可以在for循環之前(為初始化子句)或for循環末尾(為更新子句)使用單獨的語句。

?while語句(whileStatements)

一個while語句應該具有如下格式

while(condition){

statements;

1

一個空的while語句應該具有如下格式：

while(condition);

?do-while語句(do-whileStatements)

,個do-while語句應該具有如下格式：

do{

statements;

|while(condition);

switch語句(switchStatements)

一個switch語句應該具有如卜格式：

switch(condition){

caseABC:

statements;

/*fallsthrough*/

caseDEF:

statements;

break;

caseXYZ:

statements;

break;

default:

statements;

break;

I

每當一個case順著往卜執行時(因為沒有break語句)，通常應在break語句的位置添加注釋。上面的示例代

碼中就包含注釋/*fallsthrough*/c

?try-catch語句(try?catchStatements)

一個try-catch語句應該具有如下格式：

try{

statements;

}catch(ExceptionClasse){

statements;

一個try-catch語句后面也可能跟著一個finally語句，不論try代碼塊是否順利執行完，它都會被執行。

statements;

Icatch(ExceptionClasse){

statements;

}finally{

statements;

五排版格式

1.關鍵詞和操作符之間加適當的空格。

2.相對獨立的程序塊與塊之間加空行。

3.較長的語句、表達式等要分成多行書寫。

4.劃分出的新行要進行適應的縮進，使排版整齊，語句可讀。

5.長表達式要在低優先級操作符處劃分新行，操作符放在新行之首。

6.循環、判斷等語句中若有較長的表達式或語句，則要進行適應的劃分。

7.若函數或過程中的參數較長，則要進行適當的劃分。

8.不允許把多個短語句寫在一行中，即一行只寫一條語句。

9.函數或過程的開始、結構的定義及循環、判斷等語句中的代碼都要采用縮進風格。

10.用大括號'{'和'}'界定一段程序塊的，編寫程序塊時'{'和'}'應各獨占一行并且位于同

一列，同時與引用它們的語句左對齊。在函數體的開始、類的定義、結構的定義、枚舉的定義以及if、for.

do、while、switch、case語句中的程序都要采用如上的縮進方式。

六JSP編碼規范

1.整個jsp/jspbean表示層應當盡可能的瘦和簡單化。

2.牢記大多數的JSP都應當是只讀的視圖，而由頁面bean來提供模型。

3.應當一起設計JSP和JSPbean

4.在盡可能合理的情況下，把業務邏輯從JSP中移走。具體于HTTP的邏輯（如，對Cookie的處理）

屬于bean或支持類中，而不是JSP中。

5.盡量把條件邏輯放在控制器中而不是放在視圖中。

6.為JSP、包含的文件、JSPBean和實現擴展標記的類使用遵循標準的命名慣例。如：

jsp控制器xxxxConlroller.jsp

被包含的：jsp_descriptiveNameOfFragment.jsp

jsp會話bena:xxxxSessionBean

標記類:xxxxTag,xxxxTagExtra!nfo

7.應當避免設計既顯示表單乂處理結果的頁面。

8.在jsp中避免代碼重復。把要重復的功能放在一個包含的jsp、bean或標記擴展中，使得它能夠被垂

用。

9.jspbean應當永遠不要去產生HTML

10.在jsp中應該避免使用out.pringln。發放來產生頁面內容。

11.jsp層不應該直接訪問數據，這包括JDBC數據庫訪問和EJB訪問。

12.在長度上，代碼片的代碼最好不要超過10行。

13.除了jspbean之外，jsp不應當去實例化復雜的可讀寫的對象。如果這樣的話，就有可能在jsp中去

執行不適當的業務邏輯。

14.jspbean中不應當包含大量的數據。

15.如果使用了vjsp:forward＞和vjsp:include標記〉，并且必須使用簡單類型的值來與外部頁面進行通訊

的話，就應當使用?個或多個vjsp:param＞元素。

16.定制標記應當用在適合壬邏輯從jsp中移走的地方。

17.應當謹慎地使用＜jsp:forward＞標記，在jsp中它是一個等價的goto。

18.應當使用險藏的注釋來阻止輸出的HTML過大。

19.在jsp中避免進行異常處理。

20.每個jsp文件中都應當使用一個錯誤頁面來處理不能夠從中恢復的異常。

21.只有在能夠獲得性能上口勺好處時，才使用jsplnit。方法和jspDestroy。方法。獲取和放棄資源是jsp

beans和標記處理器的事，而不是由jsp來負責的。

22.如果沒有充分的理由，就不要在jsp中定義方法和內部類。

七、文件與目錄

1.所有編譯好的java類要打包成jar格式，統一放在應用目錄的WEB-INF/lib目錄下，而不能把class

文件直接放在WEB-INF/classes在錄卜"

2.系統中需要采用的第三方的類庫也應放在WEB-INF/lib目錄下，統一打包。

3.所有圖片應該放在應用目錄的images目錄下，項目和產品的圖片件放在images下的一級子目錄中，

如CMS的圖片文件可以放在images/CMSo

4.Struts的配置文件必須放在WEB-INF/config目錄下，每個產品應該有一個或多個st