軟件編碼規(guī)范

1、軟件編碼規(guī)范軟件編碼規(guī)范編 制： 莫 小 明 版 本 歷 史目錄1概述31.1.內(nèi)容31.2.編寫目的31.3.閱讀對(duì)象32java編碼命名規(guī)范42.1Package 的命名42.2Class 的命名42.3變量及方法命名42.4Static Final 變量的命名42.5參數(shù)的命名52.6數(shù)組的定義及命名52.7方法的參數(shù)52.8內(nèi)部循環(huán)變量的命名52.9JavaBean規(guī)范53java注釋規(guī)范63.1單行注釋63.2類注釋63.3方法注釋73.4變量注釋84java編碼排版規(guī)范84.1=間的空格84.2空行84.3換行94.4縮進(jìn)94.5聲明94.6括號(hào)105java編碼格式約定106數(shù)據(jù)

2、庫(kù)編碼命名規(guī)范126.1大小寫說(shuō)明126.2數(shù)據(jù)庫(kù)表命名126.3視圖命名126.4自定義函數(shù)命名126.5PL/SQL 存儲(chǔ)過(guò)程命名126.6JAVA存儲(chǔ)過(guò)程命名126.7數(shù)據(jù)庫(kù)包命名136.8自定義類型命名136.9字段名命名136.10字段別名137數(shù)據(jù)庫(kù)SQL語(yǔ)句格式137.1大小寫說(shuō)明137.2INSERT INTO 語(yǔ)句147.3UPDATE 語(yǔ)句147.4SELECT 語(yǔ)句148補(bǔ)充說(shuō)明異常拋出158.1Service層異常的拋出158.2控制層異常的處理169方法修飾說(shuō)明1610調(diào)用過(guò)程說(shuō)明171 概述1.1. 內(nèi)容本規(guī)范說(shuō)明書從大方面來(lái)說(shuō)包括：java編碼規(guī)范、數(shù)據(jù)庫(kù)表、字段

3、等的命名、SQL語(yǔ)句排版，以及后面補(bǔ)充的一些說(shuō)明。1.2. 編寫目的編碼規(guī)范對(duì)于程序員而言尤為重要，有以下幾個(gè)原因：Ø 一個(gè)軟件的生命周期中，80%的花費(fèi)在于維護(hù)。Ø 幾乎沒有任何一個(gè)軟件，在其整個(gè)生命周期中，均由最初的開發(fā)人員來(lái)維護(hù)。Ø 編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼，增加可讀性，減少項(xiàng)目組中因?yàn)閾Q人而帶來(lái)的損失。Ø 如果你將源碼作為產(chǎn)品發(fā)布，就需要確任它是否被很好的打包并且清晰無(wú)誤，一如你已構(gòu)建的其它任何產(chǎn)品 。1.3. 閱讀對(duì)象本規(guī)范說(shuō)明書閱讀對(duì)象可以是開發(fā)人員、設(shè)計(jì)人員、測(cè)試人員、審查代碼人員。2 java編碼

4、命名規(guī)范2.1 Package 的命名 Package 的名字應(yīng)該都是由一個(gè)小寫單詞組成。 例如： package com.soa.service.bi.fi; package com.soa.service.sox4;2.2 Class 的命名 Class 的名字必須由大寫字母開頭而其他字母都小寫的單詞組成,對(duì)于所有標(biāo)識(shí)符，其中包含的所有單詞都應(yīng)緊靠在一起，而且大寫中間單詞的首字母，一般使用名詞命名。public abstract class AbstractSox4Service /*內(nèi)容*/2.3 變量及方法命名 變量的名字必須用一個(gè)小寫字母開頭。后面的單詞用大寫字母開頭。變量一般使用名

5、詞命名，方法名一般使用動(dòng)詞命名，并帶有一定的意義，讓人一讀就懂；再者對(duì)于業(yè)界認(rèn)可的單詞或固有名詞，可直接使用。 EG 變量：userName ,方法名： getUserInformation、addNews 2.4 Static Final 變量的命名 static Final 變量的名字應(yīng)該都大寫，并且指出完整含義（給出出注釋）。 /DBConfig PATH public static final String DB_CONFIG_FILE_PATH ="com.neu.etrain.dbconfig"2.5 參數(shù)的命名 參數(shù)的名字必須和變量的命名規(guī)范一致。 2.6 數(shù)

6、組的定義及命名 數(shù)組應(yīng)該總是用下面的方式來(lái)命名： byte buffer; 而不是： byte buffer;2.7 方法的參數(shù) 使用有意義的參數(shù)命名，如果可能的話，使用和要賦值的字段一樣的名字： setCounter(int size) this.size = size;2.8 內(nèi)部循環(huán)變量的命名Ø 請(qǐng)不要用i、j、n等沒有意義的變量命名；Ø 不要怕麻煩，請(qǐng)使用帶有意義的單詞命名；Ø 如：userListSize、rowLength等來(lái)命。2.9 JavaBean規(guī)范Ø 一個(gè)javaBean類必須是一個(gè)公共類，類都得設(shè)置為public ；Ø

7、一個(gè)javaBean類必須有一個(gè)空的構(gòu)造函數(shù)，必須有一個(gè)不帶有參數(shù)的公用構(gòu)造器。此構(gòu)造器也應(yīng)該通過(guò)調(diào)用各個(gè)特性的設(shè)置方法來(lái)設(shè)置特性的缺省值；Ø 一個(gè)javaBean類不應(yīng)有公共實(shí)例變量，類變量都為private，變量的命名上面已經(jīng)說(shuō)明清楚；Ø 持有值應(yīng)該通過(guò)一組存取方法（getXxx和setXxx）來(lái)訪問(wèn)，對(duì)于需要的每個(gè)特性，應(yīng)該有一個(gè)帶有匹配公用getter 和setter 方法的專用實(shí)例變量。3 java注釋規(guī)范233.1 單行注釋注釋要簡(jiǎn)單明了。/用戶名String userName = null; 3.2 類注釋/* * 功能描述：寫上你的描述，至少能看懂本類是做什

8、么的，有哪些功能 * * see * 與該類相關(guān)的類，寫出具體的路徑：包括完整的包名和類名.java * * author (作者) 寫上你的姓名 * * company (開發(fā)公司) 重慶斯歐(SOA)信息技術(shù)有限公司</p> * * copyright (版權(quán)) 本文件歸屬重慶斯歐(SOA)信息技術(shù)有限公司所有</p> * * since (該版本支持的JDK版本) ： 1.5 * * version (版本) * * date (開發(fā)日期) 寫上編寫日期 * * modify (修改) * <p>第一次修改：時(shí)間、修改人;修改內(nèi)容簡(jiǎn)介 </p&g

9、t; * <p>第二次修改：時(shí)間、修改人;修改內(nèi)容簡(jiǎn)介 </p> * <p>第三次修改：時(shí)間、修改人;修改內(nèi)容簡(jiǎn)介 </p> * * Review (審核人)： * */3.3 方法注釋/* * 方法描述* param args array of string arguments* return No return value* exception exceptions No exceptions thrown*/public static void main(String args) System.out.println(“Hello worl

10、d !”);如上示例，必須有：Ø 方法功能的基本描述Ø 每個(gè)參數(shù)的說(shuō)明Ø 異常的說(shuō)明Ø 返回值的說(shuō)明3.4 變量注釋對(duì)于普通變量的注釋：/用戶姓名String username “xyz”;/用戶姓名String username “xyz”;對(duì)于類變量的注釋：/* XXXXXX */String username “xyz”;4 java編碼排版規(guī)范44.1 =間的空格關(guān)鍵詞和變量，變量和操作符之間加一個(gè)的空格Options opt1 = null;4.2 空行 空行將邏輯相關(guān)的代碼段分隔開，以提高可讀性。下列情況應(yīng)該總是使用兩個(gè)空行：Ø 一

11、個(gè)源文件的兩個(gè)片段(section)之間Ø 類聲明和接口聲明之間 下列情況應(yīng)該總是使用一個(gè)空行：兩個(gè)方法之間Ø 方法內(nèi)的局部變量和方法的第一條語(yǔ)句之間Ø 塊注釋或單行注釋之前Ø 一個(gè)方法內(nèi)的兩個(gè)邏輯段之間，用以提高可讀性4.3 換行當(dāng)一個(gè)表達(dá)式無(wú)法容納在一行內(nèi)時(shí)，可以依據(jù)如下一般規(guī)則斷開之：Ø 在一個(gè)逗號(hào)后面斷開Ø 在一個(gè)操作符前面斷開Ø 寧可選擇較高級(jí)別(higher-level)的斷開，而非較低級(jí)別(lower-level)的斷開4.4 縮進(jìn)對(duì)不同級(jí)別縮進(jìn)一個(gè)TAB4.5 聲明推薦一行一個(gè)聲明，因?yàn)檫@樣以利于寫注釋。亦即

12、，/ indentation levelint level; / size of tableint size; 要優(yōu)于，int level, size; 不要將不同類型變量的聲明放在同一行，例如： int foo, fooarray; /WRONG!4.6 括號(hào)花括號(hào)的的開始和結(jié)束均獨(dú)占一行，并上下對(duì)齊5 java編碼格式約定1. import 語(yǔ)句導(dǎo)入詳細(xì)的類名，而不是整個(gè)目錄Eg: import mon.database.DataBase;import mon.exception.DBException;import com.soa.service.bi.AbstractBIService

13、;2. 每個(gè)類、成員變量、函數(shù) 都必須加注釋。注釋的格式遵照上面的“注釋規(guī)范”3. 已經(jīng)發(fā)布的代碼中，不允許出現(xiàn)大塊的功能性注釋。如果不需要該功能，請(qǐng)直接在代碼中刪除。4. 請(qǐng)?jiān)谝呀?jīng)發(fā)布的代碼中去掉用于調(diào)試的任何代碼。5. 請(qǐng)?jiān)谝呀?jīng)發(fā)布的代碼去除所有未使用變量和函數(shù)。6. 每一個(gè)成員變量、方法體內(nèi)變量和成員函數(shù)都必須指定其作用域。關(guān)于作用域，在一些不太重視代碼質(zhì)量的人的代碼里會(huì)發(fā)現(xiàn)，一切的變量均在類里的開頭一次性定義完，或者更是極為不負(fù)責(zé)任的創(chuàng)建一大堆的對(duì)象，談到對(duì)象的創(chuàng)建，在這里說(shuō)明一下java的運(yùn)行機(jī)制，舉例：Public class APublic class B extends A B

14、 ()A a=New A(); Public class C extends BC ()A a = New A();B b =new B(); 這是一段很小的代碼，C繼承B，B又繼承A（事實(shí)上A還繼承了Object）。當(dāng)調(diào)用C的時(shí)候，在C的構(gòu)造函數(shù)里初始化了A和B，然后程序馬上又跑到B里執(zhí)行，當(dāng)在B里的時(shí)候又發(fā)現(xiàn)B的構(gòu)造函數(shù)里初始了A，然后又要執(zhí)行A的動(dòng)作，A現(xiàn)在沒任何動(dòng)作，假設(shè)A的構(gòu)造函數(shù)里又有一段比較復(fù)雜的代碼，那么這個(gè)程序?qū)⒒ㄙM(fèi)大量時(shí)間在執(zhí)行。而在C里，我們也沒有執(zhí)行具體的任務(wù)，僅僅是進(jìn)入到C的狀態(tài)就做了那么多的事情。所以，在一般情況下，我們都不建議一次性做數(shù)據(jù)的初始化(除非系統(tǒng)非常強(qiáng)烈

15、的要求)，我們建議以實(shí)際情況進(jìn)行分析，合理的安排作用域是有好處的。這樣可以很好的維護(hù)，也可以提高不少的性能問(wèn)題，同時(shí)也可以排除過(guò)多的定義而導(dǎo)致混雜不清的錯(cuò)誤。同樣，在方法體內(nèi)，依然存在局部多用域問(wèn)題，平時(shí)要小心、認(rèn)真為妙。7. 為避免虛擬機(jī)差異，在聲明類的成員變量時(shí)，如果不指定其值，應(yīng)該讓其置空；Eg: private Datastore codeDs = null；8. 通常情況下。應(yīng)該使用 log4j 來(lái)輸出信息、而不是直接使用 System.out；9. 在構(gòu)造SQL 時(shí)，短小的sql語(yǔ)句盡量使用 “+”，而長(zhǎng)度較大的SQL使用StringBuffer 的append 方法；10. 方法

16、內(nèi)需要打印信息，請(qǐng)直接使用()方法輸出；11. 方法內(nèi)打印多個(gè)測(cè)試數(shù)據(jù)(如：list、map等對(duì)象數(shù)據(jù))可使用Sys.print或Sys.println方法，不提倡使用sysout.out.print；6 數(shù)據(jù)庫(kù)編碼命名規(guī)范566.1 大小寫說(shuō)明有關(guān)數(shù)據(jù)庫(kù)的命名都是用大寫。6.2 數(shù)據(jù)庫(kù)表命名任何表必須以：SOA_開頭，結(jié)尾為：_T例如：SOA_BI_FIXED_ASSET_T (固定資產(chǎn)規(guī)模趨勢(shì)表)6.3 視圖命名SOA_開頭，結(jié)尾為：_V例如：SOA_ BI _USER_V (固定資產(chǎn)規(guī)模趨勢(shì)視圖)6.4 自定義函數(shù)命名SOA_開頭，結(jié)尾為：_F例如：SOA _BI_USE

17、R_INFO_F6.5 PL/SQL 存儲(chǔ)過(guò)程命名SOA _開頭，結(jié)尾為：_P例如：SOA _BI _USER_INFO_P6.6 JAVA存儲(chǔ)過(guò)程命名SOA _開頭，結(jié)尾為：_J例如：SOA _BI _USER_J6.7 數(shù)據(jù)庫(kù)包命名SOA_開頭，結(jié)尾為：_ PKG注：在ORACLE中合理的利用包可以更易于維護(hù)、使得整體結(jié)構(gòu)更加清晰、執(zhí)行效率更高。6.8 自定義類型命名以SOA_開頭，以_CT(代表自定義類型)結(jié)尾示例：SOA_BI_USER_ADMIN_CTSOA_BI_USER_COMMON_CT6.9 字段名命名Ø 以英文名命名Ø 對(duì)于多個(gè)單詞組合的情況，以“_”分

18、隔Ø 單詞長(zhǎng)度大的使用標(biāo)準(zhǔn)簡(jiǎn)稱Ø 字段名應(yīng)該在15字母以內(nèi)Ø 字段不使用別名示例：USER_NAME（用戶名）USER_PWD（用戶密碼）6.10 字段別名7 數(shù)據(jù)庫(kù)SQL語(yǔ)句格式77.1 大小寫說(shuō)明SQL語(yǔ)句必須全部用大寫字母編寫。7.2 INSERT INTO 語(yǔ)句INSERT INTO 表名(字段1, 字段2, 字段3)VALUES(值1, 值2, 值3)注意要求：Ø 第一行為：INSERT INTO 表(表字段)Ø 第二行為：VALUES(字段所對(duì)應(yīng)的值)Ø “,”后請(qǐng)打一個(gè)空格7.3 UPDATE 語(yǔ)句UPDATE 表名 S

19、ET 字段1 = 值1, 字段2 = 值2, 字段3 = 值3WHERE 條件1AND(OR) 條件2AND(OR) 條件3注意要求：Ø 第一行 ：UPDATE 表名Ø SET設(shè)置字段值（注：如果太長(zhǎng)，請(qǐng)換行）Ø “=”兩頭請(qǐng)都打空格Ø “,”后請(qǐng)打一個(gè)空格Ø 若帶條件，單獨(dú)一行寫WHEREØ 空四個(gè)空格符，寫上第一個(gè)條件Ø 若帶多個(gè)條件，換行，敲兩個(gè)空格，寫AND 條件NØ 一行只寫一個(gè) AND 條件7.4 SELECT 語(yǔ)句SELECT 字段1，字段2,字段3FROM 表1, 表2, 表3WHERE 條件1AN

20、D(OR) 條件2AND(OR) 條件3ORDER BY 排列字段GROUP BY 分組字段 HAVING 過(guò)濾條件UNIONALLSELECT 或者(SQL標(biāo)準(zhǔn)的關(guān)聯(lián)查詢寫法)：SELECT 字段1，字段2字段3FROM 表1 INNER(LEFT、RIGHT 、FULL) JOIN 表1 ON 條件INNER(LEFT、RIGHT 、FULL) JOIN 表2 ON 條件CROSS JION 表3 (注：交叉查詢是不帶 ON 條件的)WHERE 條件1AND(OR) 條件2AND(OR) 條件3ORDER BY 排列字段GROUP BY 分組字段 HAVING 過(guò)濾條件UNIONALLSE

21、LECT 注意要求：請(qǐng)注意以上的兩種格式，該換行的請(qǐng)換行、該空格的請(qǐng)空格！建議采用第二種格式寫法(相關(guān)的鏈接查詢請(qǐng)正確的理解)知識(shí)提醒：INNER JOIN 表ON 條件 同等于oracle中的 T1.A = T2.ALEFT JOIN 表1 ON 條件同等于oracle中的 T1.A = T2.A(+)RIGHT JOIN 表1 ON 條件同等于oracle中的 (+)T1.A = T2.A8 補(bǔ)充說(shuō)明異常拋出88.1 Service層異常的拋出Ø 公開外部訪問(wèn)的方法(public)必須：throws DBException,ServiceException方法體必須為如下格式的t

22、ry catchtry/當(dāng)人為拋出異常時(shí)： throw new ServiceException("自定義拋出異常信息定義！"); catch(Exception e) throw new ServiceException("service err:"+e.getMessage();Ø 不公開訪問(wèn)的方法(private)只有在本類被使用，必須設(shè)置為private，此時(shí)異常拋出：1、如果跟數(shù)據(jù)庫(kù)相關(guān)的，則：必須：throws DBException, Exception方法體不需要再try catch。2、如果跟數(shù)據(jù)庫(kù)無(wú)關(guān)的操作，則：必須：throws Exception方法體不需要再try catch。Ø 單個(gè)數(shù)據(jù)庫(kù)操作的方法查詢、新增、編輯、