開發(fā)及設(shè)計規(guī)范手冊

技術(shù)開發(fā)規(guī)范

［草稿］

北京中科天擎信息技術(shù)有限企業(yè)

2023年11月12曰

目錄

、JAVA代碼規(guī)范.......................................................4

1.標(biāo)識符命名規(guī)范.......................................................4

1.1概述..............................................................4

1.2包名...............................................................5

1.3類名...............................................................5

1.4措施名.............................................................7

1.5域(field)名......................................................9

1.6局部變量名........................................................10

2.代碼格式............................................................10

2.1源文獻(xiàn)編碼.......................................................10

2.2行寬..............................................................11

2.3包的導(dǎo)入..........................................................11

2.4類格式............................................................11

2.5域格式............................................................11

2.5措施格式..........................................................11

2.6代碼塊格式........................................................11

3.注釋規(guī)范.............................................................15

3.1注釋vs代碼......................................................15

3.2JavaDoc.........................................................16

3.3塊級別注釋........................................................17

3.4行內(nèi)注釋..........................................................20

4最佳實(shí)踐和禁忌........................................................20

4.1每次保留口勺時候，都讓你的代碼是最美口勺.............................20

4.2使用log而不是System.out.println().............................20

4.3每個ifwhilefor等語句，都不要省略大括號。......................20

4.4善用TODO:........................................................21

4.5在需要留空的地方放一種空語句或注釋，告述讀者，你是故意的........22

4.6不要再對boolean值做truefalse判斷.............................22

4.7減少代碼嵌套層次..................................................23

4.8程序職責(zé)單一......................................................26

4.9變量H勺申明，初始化和被使用盡量放到一起...........................26

4.10縮小變量H勺作用域.................................................27

4.11盡量不要用參數(shù)來帶回措施運(yùn)算成果................................29

二、數(shù)據(jù)庫表及字段命名規(guī)范............................................30

1.數(shù)據(jù)庫表命名規(guī)范:....................................................30

2.表字段命名規(guī)范：.....................................................31

3.表設(shè)計規(guī)范：.........................................................32

4.存儲過程命名規(guī)范.....................................................34

5.存儲過程設(shè)計規(guī)范.....................................................35

6.視圖命名規(guī)范.........................................................36

7.視圖設(shè)計規(guī)范.........................................................36

8.觸發(fā)器命名規(guī)范.......................................................36

9.觸發(fā)器設(shè)計規(guī)范.......................................................37

JAVA代碼規(guī)范

Java代碼規(guī)范以SUN的原則Java代碼規(guī)范為基礎(chǔ)，本文檔中沒有闡明的地方，請參看SUN

Java原則代碼規(guī)范。假如兩邊有沖突，以本文檔為準(zhǔn)。

1.標(biāo)識符命名規(guī)范

1.1概述

標(biāo)識符的命名力爭做到統(tǒng)一、達(dá)意和簡潔。

1.1.1統(tǒng)一

統(tǒng)一是指，對于同一種概念，在程序中用同i種表達(dá)措施，例如對于供應(yīng)商，既可以用

supplier,也可以用provider,不過我們只能選定一種使用,至少在一種Java項目中保

持統(tǒng)一。統(tǒng)一是作為重要的，假如對同一概念有不一樣的表達(dá)措施，會使代碼混亂難以理

解。雖然不能獲得好的名稱，不過只要統(tǒng)一，閱讀起來也不會太困難，由于閱讀者只要理

解一次。

1.1.2達(dá)意

達(dá)意是指，標(biāo)識符能精確的體現(xiàn)出它所代表的意義，例如：newSupplier,

OrderPaymentGatewayService等;而supplierl,service2,idtts等則不是好的命名方

式。精確有兩成含義，一是對的，而是豐富。假如給一種代表供應(yīng)商的變量起名是

order,顯然沒有對的體現(xiàn)。同樣的，supplier1,遠(yuǎn)沒有targetSupplier意義豐富。

1.1.3簡潔

簡潔是指，在統(tǒng)?和達(dá)意的前提下，用盡量少的標(biāo)識符。假如不能達(dá)意，寧愿不要簡潔。

例如：theOrderMameOfTheTargetSupplierWhichlsTransfered太長，

transferedTargetSupplierOrderName則很好，不過transTgtSplOrdNm就不好了。省略元

音的縮寫方式不要使用，我們的英語往往還沒有好到看得懂奇怪的縮寫。

1.1.4駱駝法則

Java中，除了包名，靜態(tài)常量等特殊狀況，大部分狀況下標(biāo)識符使用駱駝法則，即單詞之

間不使用特殊符號分割，而是通過首字母大寫來分割。例如：SupplierName,

addNewContract.而不是supplier_name,add_new_contractn

1.1.5英文vs拼音

盡量使用通俗易懂的英文單詞，假如不會可以向隊友求援，實(shí)在不行則使用漢語拼音，防

止拼音與英文混用。例如表達(dá)歸檔,用archive比很好,用pigeonhole則不好,用

guiDang尚可接受。

1.2包名

使用小寫字母如zktqmon.settlment,不要zktqmon.Settlement

單詞間不要用字符隔開，例如zktqmon.settlment.jsfutil,而不要zktq

mon.settlement.jsf_util

1.3類名

1.3.1首字母大寫

類名要首字母大寫，例如SupplierService,PaymentOrderAction；不要

supplierService,paymentOrderAction.

1.3.2后綴

類名往往用小一樣的后綴體現(xiàn)額外H勺意思，如下表:

后綴名意義舉例

表明這個類是個服務(wù)類，里面包括了給其他類提同業(yè)

ServicePaymentOrderService

務(wù)服務(wù)口勺措施

Impl這個類是一種實(shí)現(xiàn)類，而不是接口PaymentOrderServicelmpl

Inter這個類是一種接口LifeCyclelnter

Dao這個類封裝了數(shù)據(jù)訪問措施PaymentOrderDao

Action直接處理頁面祈求，管理頁面邏輯了類UpdateOrderListAction

Listener響應(yīng)某種事件的類PaymentSuccessListener

Event這個類代表了某種事件PaymcntSuccessEvent

Servlet一種ServletPaymentCalIbackServlet

Factory生成某種對象工廠的類PaymentOrderFactory

Adapter用來連接某種此前不被支持口勺對象的類DatabaseLogAdapter

Job某種準(zhǔn)時間運(yùn)行的任務(wù)PaymentOrderCanceIJob

Wrapper這是一種包裝類，為了給某個類提供沒有的能力SelectableOrderListWrapper

Bean這是一種POJOMenuStateBean

1.4措施名

首字母小寫,如gelNameO不要GetName()

動詞在前，如gelName0,不要Namegel()

動詞前綴往往體現(xiàn)特定的含義，如下表：

前綴名意義舉例

create創(chuàng)立createOrder0

delete刪除deleteOrder()

add創(chuàng)立，暗示新創(chuàng)立的對象屬于某個集合addPaidOrder()

remove刪除rcmovcOrdcr()

init或則初始化，暗示會做些諸如獲取資源等特

initializeObjectPool

initialize殊動作

銷毀，暗示會做些諸如釋放資源的特殊

destroydestroyObjectPool

動作

open打開openConnection()

close關(guān)閉closeConnection()<

read讀取readUserName()

write寫入writeUserNameO

get獲得getName0

set設(shè)置setNameO

prepare準(zhǔn)備prepareOrderList()

copy復(fù)制copyCustomerList()

modity修改modifyActualTotalAmount()

calculate數(shù)值計算calculateCommission()

do執(zhí)行某個過程或流程doOrderCance1Job()

dispatch判斷程序流程轉(zhuǎn)向dispatchUserRequest()

start開始startOrderProccssingO

stop結(jié)束stopOrdcrProcessingO

send發(fā)送某個消息或事件sendOrderPaidMessage()

receive接受消息或時間receiveOrderPaidMessgae()

respond響應(yīng)顧客動作responseOrderListltemClieked()

find查找對象findNewSupp1ier()

update更新對象updateCommissionO

find措施在業(yè)務(wù)層盡最體現(xiàn)業(yè)務(wù)含義，例如findUnsettledOrdersO,查詢未結(jié)算訂單,

而不要findOrdersByStatus()。數(shù)據(jù)訪問層，find,update等措施可以體現(xiàn)要執(zhí)行的)

sql,例如findByStatusAndSupplierldOrderByName(Status.PAID,345)

L5域(field)名

1.5.1靜態(tài)常量

全大寫用下劃線分割，如

publicstaticfindStringORDER_PAID_EVENT="ORDER_PAID_EVENT";

1.5.2枚舉

全大寫，用下劃線分割，如

publicenumEvents{

ORDERPAID,

ORDER_CREATED

}

1.5.3其他

首字母小寫，駱駝法則，如:

publicStringorderName;

1.6局部變量名

參數(shù)和局部變量名首字母小寫，駱駝法則。盡量不要和域沖突，盡量體現(xiàn)這個變量在措施

中的j意義。

2.代碼格式

用空格字符縮進(jìn)源代碼,不要用tab,每個縮進(jìn)4個空格。

2.1源文獻(xiàn)編碼

源文獻(xiàn)使用utf-8編碼，結(jié)尾用unixn分格。

2.2行寬

行寬度不要超過130。

2.3包歐I導(dǎo)入

刪除不用的導(dǎo)入，盡量不要使用整個包的導(dǎo)入。在eclipse下常常使用快捷鍵

ctrl+shift+o修正導(dǎo)入。

2.4類格式

2.5域格式

每行只能申明一種域。

域的申明用空行隔開。

2.5措施格式

2.6代碼塊格式

2.6.1縮進(jìn)風(fēng)格

大括號的開始在代碼塊開始的行尾，閉合在和代碼塊同一縮進(jìn)的行首，例如:

packagecom.test;

publicclassTeststyleextendsSomeClass

implementsApplelnter,Bananalnter{

publicstaticfinalStringTHIS_IS_CONST="CONSTVALUE";

privatestaticvoidmain(String[]args){

intlocalvariable=0;

}

publicvoidcompute(Stringarg){

if(arg.length()>0){

(arg);

}

for(inti=0;i<10;i++){

(arg);

}

while(condition){

}

do{

otherMethod();

}while(condition);

switch(i){

case0:

callFunction();

break;

case1:

callFunctionb();

break;

default:

break;

}

}

}

2.6.2空格時使用

2.6.2.1表達(dá)分割時用一種空格

不能這樣：

if(a>b){

//dosomethinghere

}；

2.6.2.2二元三元運(yùn)算符兩邊用一種空格隔開

如下:

a+b=c;

b-d=e;

returna==b?1:0;

不能如下：

a+b=c;

b-d=e;

returna==b?l:0;

2.6.2.3逗號語句后如不還行，緊跟一種空格

如下：

call(a,b,c);

不能如下：

call(a,b,c);

2.6.3空行時使用

空行可以體現(xiàn)代碼在語義上的分割，注釋的作用范圍，等等。將類似操作，或?組操作放

在一起不用空行隔開，而用空行隔開不一樣組的代碼，如圖:

order=orderDao.findOrderByld(id);

//updateproperties

order.setUserName(userName);

order.setPrice(456);

order.setStatus(PAID);

orderService.updateTotalAmount(order);

session.saveOrUpdate(order);

上例中的空行，使注釋的作用域很明顯.

?持續(xù)兩行的空行代表更大日勺語義分割。

?措施之間用空行分割

?域之間用空行分割

?超過十行的代碼假如還不用空行分割，就會增長閱讀困難

3.注釋規(guī)范

3.1注釋VS代碼

?注釋宜少而精，不適宜多而濫，更不能誤導(dǎo)

?命名達(dá)意，構(gòu)造清晰，類和措施等責(zé)任明確，往往不需要，或者只需要很少注釋，

就可以讓人讀懂；相反，代碼混亂，再多U勺注釋都不能彌補(bǔ)。因此，應(yīng)當(dāng)先在代碼自

身下功夫。

?不能對的體現(xiàn)代碼意義日勺注釋，只會損害代碼的可讀性。

?過于詳細(xì)的注釋，對顯而易見的代碼添加U勺注釋，羅嗦的注釋，還不如不寫

O

?注釋要和代碼同步，過多的注釋會成為開發(fā)日勺承擔(dān)

?注釋不是用來管理代碼版本的，假如有代碼不要了，直接刪除，svn會有記錄的，不

要注釋掉，否則后來沒人懂得那段注釋掉日勺代碼該不該刪除。

3.2JavaDoc

表明類、域和措施等的意義和使用方法等的注釋，要以javadoc的方式來寫。JavaDec是

個類的使用者來看的，重要簡介是什么，怎么用等信息。但凡類H勺使用者需要懂得，都要

用JavaDoc來寫。非JavaDoc的注釋，往往是個代碼的維護(hù)者看H勺，著重告述讀者為何

這樣寫，怎樣修改，注意什么問題等。如下：

/**

*Thisisaclasscomment

publicclassTestclass(

**

*Thisisafieldcomment

*/

publicStringname;

/**

*Thisisamethodcomment

*/

publicvoidcall(){

3.3塊級別注釋

3.3.1塊級別注釋，單行時用II,多行時用/*..

*/o

//publicintage;

/*

publicintsetName(StringstrName)

(

name=strName;

return1;

)

*/

3.3.2較短的代碼塊用空行表達(dá)注釋作用域

3.3.3較長的代碼塊要用

/*-----start:------*/

和

/*-------end:--------*/

包圍

如：

/*---------start:訂單處理-------*/

〃獲得dao

OrderDaodao=Factory.getDao("OrderDao");

/*查詢訂單*/

Orderorder=dao.findById(456);

〃更新訂單

order.setUserName("uu");

order.setPassword("pass");

order.setPrice("ddd");

orderDao.save(order);

/*---------pnd:訂單處理-------*/

3.3.4可以考慮使用大括號來表達(dá)注釋范圍

使用大括號表達(dá)注釋作用范圍的例子：

/*----......訂單處理-------*/

{

〃獲得dao

OrderDaodao=Factory.getDao("OrderDao");

/*查詢訂單*/

Orderorder=dao.findByld(456);

〃更新訂單

order.setUserName("uu");

order.setPassword("pass");

order.setPrice("ddd");

orderDao.save(order);

}

3.4行內(nèi)注釋

行內(nèi)注釋用〃寫在行尾

publicStringname;〃姓名

4最佳實(shí)踐和禁忌

4.1每次保留的時候，都讓你的代碼是最美的

程序員都是懶惰的，不要想著等我完畢了功能，再來優(yōu)化代碼的格式和構(gòu)造，等真的把功

能完畢，很少有人會再樂意回頭調(diào)整代碼。

4.2使用log而不是System,out.printlnO

log可以設(shè)定級別，可以控制輸出到哪里，輕易辨別是在代碼口勺什么地方打印H勺，而貝］不

行。并且，的速度很慢。因此，除非是故意的，否則，都要用log。至少在提交到svn之

前把換成logo

4.3每個ifwhilefor等語句，都不要省略

大括號{}

看下面的代碼:

if(a>b)

a++;

假如在后來維護(hù)日勺時候，需要在a>b時，把b++,一步小心就會寫成:

if(a>b)

a++;

b++;

這樣就錯了，由于無論a和b是什么關(guān)系，b++都會執(zhí)行。假如一開始就這樣寫:

if(a>b){

}

相信沒有哪個笨蛋會把b++添加錯的。并且，這個大括號使作用范圍更明顯，尤其是背面

那行很長要折行時。

4.4善用TODO:

在代碼中加入〃TODO:,大部分『、Jid。都會幫你提醒，讓你懂得你尚有什么事沒有做。例

如:

if(order.isPaid()){

〃TODO：更新訂單

}

4.5在需要留空時地方放一種空語句或注釋,

告述讀者，你是故意的I

例如:

if(Sexists(order)){

}

或:

if(Sexists(order)){

//nothingtodo

}

4.6不要再對boolean值做truefalse判斷

例如：

if(order,.ibPdid()==Irue){

//Dosomethinghere

}

不如寫成：

if(order.isPaid()){

//Dosomethinghere

}

后者讀起來就很是iforderispaid,....要比iforder*sisPaidmethodreturns

true,???更輕易理解

4.7減少代碼嵌套層次

代碼嵌套層次達(dá)3層以上時，一般人理解起來都會困難.下面的代碼是一種簡樸臥J例子:

publicvoiddemo(inta,intb,intc){

if(a>b){

if(b>c){

do3obA();

}elseif(b<c){

do3obB()

}

}else{

if(b>c){

if(a<c){

do3obC();

}

}

}

}

減少嵌套的措施有諸多：

?合并條件

?運(yùn)用return以省略背面口勺else

?運(yùn)用子措施

例如上例，合并條件后成為：

publicvoiddemo(inta,intb,intc){

if(a>b&&b>c){

do3obA();

}

if(a>b&&c>b){

doJobB();

}

if(a<=b&&c<b&&a<c){

do3obC();

}

}

假如運(yùn)用return則成為：

publicvoiddemo(inta,intb,intc)

if(a>b){

if(b>c){

do3obA();

return;

}

do3obB()

return;

}

if(b>c){

if(a<c){

do3obC();

}

}

}

運(yùn)用子措施，就是將嵌套的程序提取出來放到此外日勺措施里。

4.8程序職責(zé)單一

關(guān)注點(diǎn)分離是軟件開發(fā)的真理。人類自因此可以完畢復(fù)雜的工作，就是由于人類可以將工

作分解到較小級別H勺仟務(wù)卜.在做每個仟務(wù)時關(guān)注更少H勺東西.計程序單元H勺職責(zé)單一.

可以使你在編寫這段程序時關(guān)注更少日勺東西，從而減少難度，減少出錯。

4.9變量的申明，初始化和被使用盡量放到一

起

比方說如下代碼：

intorderNum=getOrderNum();

//dosomethingwithouorderNumhere

call(orderNum);

上例中的注釋處代表了一段和orderNum不有關(guān)的代碼。orderNum的申明和初始化離被使

用的地方相隔了諸多行的代碼，這樣做不好，不如這樣:

//dosomethingwithouorderNumhere

intorderNum=getOrderNum();

call(orderNum);

4.10縮小變量的作用域

能用局部變量IJ勺，不要使用實(shí)例變量，能用實(shí)例變量"勺，不要使用類變量。變量的生存期

越短，認(rèn)為著它被誤用的機(jī)會越小，同一時刻程序員要關(guān)注的變量的狀態(tài)越少。實(shí)例變量

和類變量默認(rèn)都不是線程安全I(xiàn)I勺，局部變量是線程安全I(xiàn)I勺。例如如下代碼：

publicclassOrderPayAction{

privateOrderorder;

publicvoiddoAction(){

order=orderDao.findOrder();

do3obl();

do3ob2();

}

privatevoiddo3obl(){

doSomething(order);

)

privatevoiddo3ob2(){

doOtherThing(order);

}

}

上例中order只不過擔(dān)當(dāng)了在措施間傳遞參數(shù)之用，用下面日勺措施更好:

publicclassOrderPayAction{

publicvoiddoAction(){

order=orderDao.findOrder();

do3obl(order);

do3ob2(order);

)

privatevoiddoJobl(Orderorder){

doSomething(order);

}

privatevoiddoJob2(Orderorder){

doOtherThing(order);

}

4.11盡量不要用參數(shù)來帶回措施運(yùn)算成果

例如：

publicvoidcalculate(Orderorder){

intresult=0;

//dolotsofcomputingandstoreitintheresult

order.setResult(result);

}

publicvoidaction(){

order=orderDao.findOrder();

calculate(order);

//dolotsofthingsaboutorder

}

例子中calculate措施通過傳入的order對象來存儲成果，不如如下寫:

publicintcalculate(Orderorder){

intresult=0;

//dolotsofcomputingandstoreitintheresult

returnresult;

}

publicvoidaction(){

order=orderDao.findOrder();

order.setResult(calculate(order));

//dolotsofthingsaboutorder

}

二、數(shù)據(jù)庫表及字段命名規(guī)范

1.數(shù)據(jù)庫表命名規(guī)范：

(D表名前應(yīng)當(dāng)加上前綴，表口勺前綴一種用系統(tǒng)或模塊的英文名稱縮寫，表名前綴和所有單

詞所有小寫。

oa_mess_lmessage

(2)數(shù)據(jù)庫表名應(yīng)當(dāng)故意義，并且易于理解，最佳使用可以體現(xiàn)功能日勺英文單詞或縮寫，假

如用英文單詞表達(dá)，提議使用完整日勺英文單詞。

(3)表名不可以太長，最佳不要超過3個英文單詞長度(22個字母)。

(4)在數(shù)據(jù)庫表命名時應(yīng)當(dāng)用英文單詞H勺單數(shù)形式，如員工表命名：應(yīng)當(dāng)為employee而不

是employees.

(5)假如是后臺表命名時應(yīng)當(dāng)在表名基礎(chǔ)上加上后綴

_b

(back首字母)

(6)在表創(chuàng)立完畢前，應(yīng)當(dāng)為表添加表的注釋。

2.表字段命名規(guī)范：

(1)數(shù)據(jù)庫表字段應(yīng)當(dāng)是故意義并且易于理解H勺，最佳是可以體現(xiàn)字段含義的英文字母

(有人認(rèn)為假如用英文單詞作為字段，由于翻譯工具不一樣，而字段不統(tǒng)一提議使用漢語

拼音首字母縮寫

；有人認(rèn)為用漢語拼音縮寫看起來不直觀，老半天也不懂得究竟這個字段是干什么的J)

(2)系統(tǒng)中所有屬于內(nèi)碼，即僅用于標(biāo)識唯一性和程序內(nèi)部用到日勺標(biāo)識性字段，字段名稱提

議取為ID,采用類型為整型或長整型.

(3)系統(tǒng)中屬于是業(yè)務(wù)內(nèi)的編號字段，代表一定業(yè)務(wù)信息，提議字段命名為

code,如工作單編號

wfcode.

(4)不要在數(shù)據(jù)庫表字段(列名)中包括數(shù)據(jù)類型，如：datetime

（5）不要在數(shù)據(jù)庫表字段1列名）命名時反復(fù)表名，可以使用表名首字母（不包括數(shù)據(jù)庫表

名前綴）

注意：

不要在數(shù)據(jù)庫表字段（列名）命名時

不提議使用數(shù)據(jù)庫關(guān)鍵字:如:name,time,datetimepassword等

3.表設(shè)計規(guī)范：

（1）所有字段在設(shè)計時，除如下數(shù)據(jù)類型timestamp、image、datetime>smal1datetime>

uniqueidentifier>binary>sql_variant>binary>varbinary外,必須有默認(rèn)值。字符

型的默認(rèn)值為一種空字符值串；數(shù)值型的默認(rèn)值為數(shù)值0;邏輯型的默認(rèn)值為數(shù)值（）；

其中：系統(tǒng)中所有邏輯型中數(shù)值0表達(dá)為“假”；數(shù)值1表達(dá)為“真”。

datetime、smalldatctime類型的字段沒有默認(rèn)值，必須為NULL。

（2）當(dāng)字段定義為字符串形時提議使用varchar而不用nvarcharo

注

：在MySQL5.0以上口勺版本中，varchar數(shù)據(jù)類型為長度支持到了65535,也就

是說可以寄存65532個字節(jié)口勺數(shù)據(jù)，起始位和結(jié)束位占去了3個

字節(jié)。

（3）提議在大多數(shù)