JAVA編碼規(guī)范V10

1、java 編碼規(guī)范目錄1 說明31.1 版本說明31.1.1v1.031.2 文檔閱讀說明32 項目規(guī)范32.1 項目編碼33 java規(guī)范33.1 構(gòu)建33.2 代碼架構(gòu)43.3 排版43.4 注釋53.5 命名73.6 編碼93.7 性能與牢靠性144 附錄錯誤 .未定義書簽；4.1 代碼治理規(guī)范錯誤 .未定義書簽；4.2 myeclipse 優(yōu)化設(shè)置錯誤 .未定義書簽；1 說明1.1 版本說明1.1.1 v1.0初始版本，依據(jù)2021 年公司 j2ee版本規(guī)范修訂而來；去除了javascript 規(guī)范（該部分規(guī)劃為將來單獨整理）；去除了代碼評審相關(guān)評審表格（這部分該由項目治理流程供應(yīng)）；

2、去除了項目目錄規(guī)劃部分的描述（該規(guī)劃后續(xù)單獨供應(yīng)） ；1.2 文檔閱讀說明r：規(guī)章，必需遵守 s：建議，依據(jù)實際情形而定2 項目規(guī)范2.1 項目編碼項目編碼統(tǒng)一使用utf-8 進行編碼，包括java、jsp、js、css、properties 、xml 等；3 java 規(guī)范3.1 構(gòu)建r1 java項目均應(yīng)采納maven 進行項目構(gòu)建，并能實現(xiàn)通過命令行自動構(gòu)建；說明： 采納 maven 或 gradle 進行項目構(gòu)建是java項目開發(fā)工作自動化的常見選項；gradle 目前普及程度不及 maven；故此公司打算采納maven 作為項目構(gòu)建的基礎(chǔ)工具；將來推廣自動構(gòu)建、連續(xù)集成、代碼自動審查

3、等工作，均依靠于項目最基礎(chǔ)的標(biāo)準(zhǔn)化工作；期望大家遵守；3.2 代碼架構(gòu)s1 假如類在當(dāng)前定義文件外被使用，就需要定義為public說明： java強制要求每個java文件中有一個public 類型的類；因此，public 類和 java文件具有一一對應(yīng)關(guān)系；這背后隱含著java語言舉薦的代碼組織規(guī)章；我們在編碼過程中，也應(yīng)盡量遵循該規(guī)章，防止非 public 類在當(dāng)前定義文件外被使用的情形；假如需要被當(dāng)前定義文件外的類使用，請聲明為public ，以增加代碼可讀性；3.3 排版r1程序塊要采納縮進風(fēng)格編寫，代碼縮進單位為4 個空格，不使用tab 縮進；說明：縮進使程序更易閱讀，由于開發(fā)工具及開

4、發(fā)操作系統(tǒng)環(huán)境統(tǒng)一，所以不使用tab 縮進；【注】采納tab 鍵和 space鍵進行縮進是常常發(fā)生爭議的地方；毫無疑問tab 鍵縮進的便利性遠超 space鍵；但是考慮到常用的代碼審查工具都建議采納space而不是 tab 縮進；因此， 為了將來代碼格式化和代碼審查的便利，規(guī)定采納空格縮進的方式；可在開發(fā)工具中設(shè)置采用 4 個空格鍵替換tabr2左分界符（如大括號）應(yīng)在語句同一行，并與語句間隔一個空格，右分界符（如大括號 ）獨占一行，同時與引用它們的語句左對齊；在函數(shù)體的開頭、類和接口的定義、 以及 if 、for 、do、while 、switch 、case 語句中的程序或者static

5、、,synchronized 等語句塊中都要采納如上的縮進方式；示例:if a>b dostart;r3每行語句字符不超過100 字符， 對于較長的語句、表達式或參數(shù)要分成多行書寫，換行應(yīng)遵循逗號后面， 操作符前面的原就；示例：if logger.isdebugenabled logger.debug"session destroyed,call-id"+ event.getsession.getcallid;r4不答應(yīng)把多個短語句寫在一行中，即一行只寫一條語句；說明：閱讀代碼更加清晰示例：如下例子不符合規(guī)范；object o = new object; object

6、 b = null;r5if, for, do, while, case, switch, default等語句自占一行，且if, for, do, while,switch等語句的執(zhí)行語句無論多少都要加括號,case 的執(zhí)行語句中假如定義變量必需加括號；說明：閱讀代碼更加清晰，削減錯誤產(chǎn)生示例：if a>b dostart;case x: int i = 9;【注】這里需要特殊說明的是一種被稱作if then 的情形；r6在兩個以上的關(guān)鍵字、變量、常量進行對等操作時，它們之間的操作符之前、之后或者前后要加空格； 進行非對等操作時，假如是關(guān)系親密的立刻操作符（如.），后不應(yīng)加空格；說明：

7、閱讀代碼更加清晰示例：if a = b objecta.d ostart;a*= 2;s1類屬性和類方法不要交叉放置，不同存取范疇的屬性或者方法也盡量不要交叉放置；格式：類定義類的靜態(tài)屬性定義類的靜態(tài)方法定義類的私有屬性定義類的愛護屬性定義類的公有屬性定義類的私有方法定義類的愛護方法定義類的公有方法定義s2修飾詞依據(jù)指定次序書寫：拜訪權(quán)限 staticfinal；示例：public static final string str =“ abc ”;s3可以使用myeclipse 或 eclipse 自帶的ctrl+shift+f 來自動格式化編碼排版，格式化后請仔細檢查一下；說明：留意假如使用

8、搜狗輸入法，請確認與其快捷鍵不沖突，具體參照：3.4 注釋r1類和接口的注釋放在class 或者interface關(guān)鍵字之前，import關(guān)鍵字之后；注釋主要是功能簡述；類注釋使用“ /*/ ”注釋方式；說明：類和接口注釋要著重功能描述、作者、交付后修改記錄；/* 功能簡述* author 作者 （必需）*/示例：package m; import java.util.date;/* logmanager類集中掌握對日志讀寫的操作；* author張三，李四，王五*/public class logmanagerr2類屬性 成員變量 、公有和愛護方法注釋：寫在類屬性、公有和愛護方法上面，注釋方

9、式為“/*/ ”；示例：/*注釋內(nèi)容*/private string logtype;/*注釋內(nèi)容*/public void writer3公有和愛護方法注釋內(nèi)容：列出方法的一句話功能簡述、功能具體描述、輸入?yún)?shù)、輸出參數(shù)、返回值、反常等；格式：/* 功能簡述* param 參數(shù) 1參數(shù) 1 說明 * param 參數(shù) 2參數(shù) 2 說明 * return返回類型說明* exception/throws 反常類型 反常說明 */示例：/* 依據(jù)日志類型和時間讀取日志；* 安排對應(yīng)日志類型的logreader， 指定類型、查詢時間段、條件和反復(fù)器緩沖數(shù)，* 讀取日志記錄；查詢條件為null 或 0

10、 的表示沒有限制，反復(fù)器緩沖數(shù)為0 讀不到日志；* 查詢時間為左包含原就，即starttime, endtime；* param logtypename日志類型名（在配置文件中定義的）* param starttime查詢?nèi)罩镜拈_頭時間* param endtime查詢?nèi)罩镜慕K止時間* param loglevel查詢?nèi)罩镜募墑e* param username查詢該用戶的日志* param buffernum日志反復(fù)器緩沖記錄數(shù)* return結(jié)果集，日志反復(fù)器*/public static logiterator readstring logtype, date starttime,date

11、 endtime, int loglevel, string username, int buffernumr4對于方法內(nèi)部用throw 語句拋出的反常，必需在方法的注釋中標(biāo)明，對于所調(diào)用的其他方法所拋出的異常，挑選主要的在注釋中說明；對于非runtimeexception ，即 throws子句聲明會拋出的反常，必需在方法的注釋中標(biāo)明；說明：反常注釋用exception 或throws 表示，在javadoc 中兩者等價，但舉薦用exception 標(biāo)注 runtime反常， throws 標(biāo)注非runtime 反常；反常的注釋必需說明該反常的含義及什么條件下拋出該反常；r5注釋應(yīng)與其描述的

12、代碼相近，對代碼的注釋應(yīng)放在其上方，并與其上面的代碼用空行隔開，注釋與所描述內(nèi)容進行同樣的縮排；說明：可使程序排版整齊，并便利注釋的閱讀與懂得；示例：/* 注釋*/public void example2 /注釋codeblock one/注釋codeblock two/* 注釋*/public void example /注釋codeblock one/注釋codeblock twor6修改代碼同時修改相應(yīng)的注釋，以保證注釋與代碼的一樣性；r7防止在注釋中使用縮寫，特殊是不常用縮寫；說明：在使用縮寫時或之前，應(yīng)對縮寫進行必要的說明；r8對重寫父類的方法必需進行override 聲明；說明：可

13、清晰說明此方法是重寫父類的方法，保證重寫父類的方法時不會由于單詞寫錯而造成錯誤寫錯方法名或者參數(shù)個數(shù)，類型都會編譯無法通過示例：overridepublic void dorequestsipservletrequest req throws servletexception, ioexceptionr9 對于需要注釋掉（不使用）的代碼，應(yīng)使用 / 注釋，而不是 /*/ 注釋考慮到對 scm系統(tǒng)（ svn等）的友好，注釋掉的代碼段，應(yīng)采納 / 而不是 /*/ ，由于采納 /*/ 注釋，修改的代碼行只有首位兩行， 中間的代碼段無任何變化； 這樣 svn 工具無法判定出實際所做的修改； 而通過 /

14、 注釋的代碼，必需逐行注釋，在 svn 工具中可以很簡潔判定出整個被注釋掉的代碼段；這對于依靠svn 等 scm 系統(tǒng)進行代碼審查的工作來說，是很有價值的；s1在代碼的功能、意圖層次上進行注釋，供應(yīng)有用、額外的信息；說明：注釋的目的是說明代碼的目的、功能和采納的方法，供應(yīng)代碼以外的信息，幫忙讀者懂得代碼，防止沒必要的重復(fù)注釋信息；/假如receiveflag 為真if receiveflag而如下的注釋就給出了額外有用的信息；/假如從連結(jié)收到消息if receiveflag【注】這一條存在爭議；依據(jù)目前比較主流的思路；代碼本身應(yīng)當(dāng)是具有自說明才能；通過使用商定俗成的設(shè)計模式、命名規(guī)范和代碼格式

15、，體會豐富的代碼編寫和閱讀者能夠順當(dāng)?shù)?讀懂代碼，不需要太多注釋；甚至可以認為，注釋寫的過多，說明代碼的規(guī)律和可讀性可能 存在問題；同時，需要留意的一點是：不要將注釋等同于文檔；注釋可以簡練精致甚至不寫；但對類、方法的描述屬于文檔層面，其重要性和必要性不應(yīng)存在爭議；示例：如下注釋意義不大；s2對關(guān)鍵變量的定義和分支語句（條件分支、循環(huán)語句等）編寫注釋；說明： 這些語句往往是程序?qū)崿F(xiàn)某一特定功能的關(guān)鍵，對于愛護人員來說，良好的注釋幫忙更好的懂得程序，有時甚至優(yōu)于看設(shè)計文檔；注釋應(yīng)考慮程序易讀及外觀排版的因素，使用的語言如是中、英兼有的，建議多使用中文，除非能用特別流利精確的英文表達；中文注釋中需

16、使用中文標(biāo)點；方法和類描述的第一句話盡量使用簡潔明白的話概括一下功能，然后加以句號；接下來的部分可以具體描述；說明：注釋語言不統(tǒng)一，影響程序易讀性和外觀排版，出于對愛護人員的考慮，建議使用中文；javadoc工具收集簡介的時候使用選取第一句話；s3一些復(fù)雜的代碼需要說明；示例：這里主要是對閏年算法的說明；/1.假如能被4 整除，是閏年；/ 2. 假如能被100 整除，不是閏年；/ 3. 假如能被400 整除，是閏年；3.5 命名r1類名和接口使用意義完整的英文描述，每個英文單詞的首字母使用大寫、其余字母使用小寫的大小寫混合法；（ pascal命名法）示例： orderinformation,

17、customerlist, logmanager, logconfig, smptransactionr2方法名使用類意義完整的英文描述：第一個單詞的字母使用小寫、剩余單詞首字母大寫、其余字母小寫；（駝峰命名法） 示例：private void calculaterate; public void addneworder;r3方法中，存取屬性的方法采納setter和 getter 方法，動作方法采納動詞和動賓結(jié)構(gòu)；格式：get + 非布爾屬性名 is + 布爾屬性名 set + 屬性名 動詞 動詞+ 賓語 示例：public string gettype; public boolean isf

18、inished;public void setvisibleboolean;public void show;public void addkeylistenerlistener;r4屬性名使用意義完整的英文描述，第一個單詞的字母使用小寫，剩余單詞首字母大寫其余字母小寫的大小寫混合法；屬性名不能與方法名相同；示例：private customername; private ordernumber; private smpsession;r5常量名使用全大寫的英文描述，英文單詞之間用下劃線分隔開，并且使用static final 修飾；示例：public static final int max

19、_value = 1000;public static final string default_start_date = "2001-12-08"s1包名采納域后綴倒置的加上自定義的包名，采納小寫字母，都應(yīng)當(dāng)以com.botech開頭 不包括一些特殊緣由 ；說明：除特殊緣由包結(jié)構(gòu)都必需以com.botech 開頭；格式：com.botech. 產(chǎn)品名 .模塊名稱示例：證據(jù)系統(tǒng)融合pgis 包名of.pgiss2通過對函數(shù)或過程、變量、結(jié)構(gòu)等正確的命名以及合理地組織代碼的結(jié)構(gòu)，使代碼成為自注釋的；說明：清晰精確的函數(shù)、變量等的命名，可增加代碼可讀

20、性，并削減不必要的注釋；s3常用組件類的命名以組件名加上組件類型名結(jié)尾；示例：application類型的，命名以app 結(jié)尾 mainapp frame 類型的，命名以frame 結(jié)尾 topoframepanel 類型的，建議命名以panel 結(jié)尾 createcircuitpanelbean 類型的，建議命名以bean 結(jié)尾 dataaccessbean ejb 類型的，建議命名以ejb 結(jié)尾 dbproxyejbapplet類型的，建議命名以applet結(jié)尾 pictureshos4假如函數(shù)名超過15 個字母，可采納以去掉元音字母的方法或者以行業(yè)內(nèi)商定俗成的縮寫方式縮寫函數(shù)名；示例：g

21、etcustomerinformation改為getcustomerinfos5精確地確定成員函數(shù)的存取掌握符號:只是該類內(nèi)部調(diào)用的函數(shù)使用private屬性， 繼承類可以使用的使用 protected 屬性，同包類可以調(diào)用的使用默認屬性不加屬性掌握符號，對外公開的函數(shù)使用public 屬性；示例：protected void getusername ；private void calculaterate ；s6含有集合意義的屬性命名，盡量包含其復(fù)數(shù)的意義；示例：customers,orderitems3.6 編碼r1對于 switch 語句下的case 語句，必需在每個case 分支終止前加

22、上break 語句；說明： break 才能真正表示該switch 執(zhí)行終止，不然可能會進入該case 以后的分支；至于語法上合法的場景“一個 case 后進入下一個case 處理”，應(yīng)當(dāng)在編碼設(shè)計上就防止；r1 數(shù)據(jù)庫操作、 io 操作等需要使用終止 close的對象必需在 try -catch-finally 的 finally 中 close，假如有多個 io 對象需要 close，需要分別對每個對象的 close方法進行 try-catch, 防止一個 io 對象關(guān)閉失敗其他 io 對象都未關(guān)閉；示例：try / . . catchioexception ioe /. . finall

23、y try try out.close; catch ioexception ioe /. .in.close; catch ioexception ioe /. .r2系統(tǒng)非正常運行產(chǎn)生的反常捕捉后，假如不對該反常進行處理，就應(yīng)當(dāng)記錄日志；說明：此規(guī)章指通常的系統(tǒng)非正常運行產(chǎn)生的反常，不包括一些基于反常的設(shè)計；如有特殊緣由必需用注釋加以說明；示例：try /. . catch ioexception ioe logger.errorioe;【注】不只是出反常了需要打印日志，對于重要的業(yè)務(wù)， 在操作前和操作后都需要記錄日志：logger.infor3自己拋出的反常必需要填寫具體的描述信息；說明

24、：便于問題定位；示例：throw newioexception"writing data error. data: " + data.tostring;r4運行時反常使用runtimeexception 的子類來表示， 不用在可能拋出反常的方法聲明上加throws 子句；非運行期反常是從exception 繼承而來的，必需在方法聲明上加throws 子句；說明：非運行期反常是由外界運行環(huán)境打算反常拋出條件的反常，例如文件操作，可能受權(quán)限、磁盤空間大小的影 響而失敗，這種反常是程序本身無法防止的，需要調(diào)用者明確考慮該反常顯現(xiàn)時該如何處理方法，因此非運 行期反常必需有throw

25、s 子句標(biāo)出，不標(biāo)出或者調(diào)用者不捕捉該類型反常都會導(dǎo)致編譯失敗，從而防止程序員本身疏忽；運行期反常是程序在運行過程中本身考慮不周導(dǎo)致的反常，例如傳入錯誤的參數(shù)等；拋出運行期反常的目的是防止反常擴散，導(dǎo)致定位困難；因此在做反常體系設(shè)計時要依據(jù)錯誤的性質(zhì)合理挑選自定義反常的繼承關(guān)系；仍有一種反常是error 繼承而來的，這種反常由虛擬機自己愛護，表示發(fā)生了致命錯誤，程序無法連續(xù)運行例如內(nèi)存不足；我們自己的程序不應(yīng)當(dāng)捕捉這種反常，并且也不應(yīng)當(dāng)創(chuàng)建該種類型的反常；r5在程序中使用反常處理仍是使用錯誤返回碼處理，依據(jù)是否有利于程序結(jié)構(gòu)來確定，并且反常和錯誤碼不應(yīng)當(dāng)混合使用，舉薦使用反常；說明：一個系統(tǒng)或

26、者模塊應(yīng)當(dāng)統(tǒng)一規(guī)劃反常類型和返回碼的含義；但是不能用反常來做一般流程處理的方式，不要過多地使用反常，反常的處理效率比條件分支低，而且反常的跳轉(zhuǎn)流程難以猜測；留意： java 5.0 程序內(nèi)部的錯誤碼可以使用枚舉來表示；r6留意運算符的優(yōu)先級，并用括號明確表達式的操作次序，防止使用默認優(yōu)先級； 說明：防止閱讀程序時產(chǎn)生誤會，防止因默認的優(yōu)先級與設(shè)計思想不符而導(dǎo)致程序出錯；示例：以下語句中的表達式word = high << 8 | low1 if a | b && a & c2if a | b < c & d3假如書寫為high <<

27、 8 | low a | b && a & c a | b < c & d（1 ）（ 2）雖然不會出錯，但語句不易懂得；（ 3）造成了判定條件出錯；r7防止使用不易懂得的數(shù)字，用有意義的標(biāo)識來替代；涉及物理狀態(tài)或者含有物理意義的常量，不應(yīng)直接使用數(shù)字，必需用有意義的靜態(tài)變量或者枚舉來代替；示例：如下的程序可讀性差；if state = 0 state = 1;./ program code應(yīng)改為如下形式：private final static int trunk_idle = 0; private final static int trunk_busy

28、= 1;private final static int trunk_unknown = -1;if state = trunk_idle state = trunk_busy;./ program code留意： java 5.0 下建議使用枚舉來表示；反常：public void function .throw new runtimeexception “；”;r8數(shù)組聲明的時候使用int index，而不要使用int index；說明：使用int index格式使程序的可讀性較差，int index表示聲明白一個int 數(shù)組 int 叫做 index示例：如下程序可讀性差：public

29、int getindex .如下程序可讀性好：public int getindex .r9不要使用system.out與system.err進行掌握臺打印，應(yīng)當(dāng)使用工具類如：日志工具進行統(tǒng)一記錄或者打??；說明：代碼發(fā)布的時候可以統(tǒng)一關(guān)閉掌握臺打印，代碼調(diào)試的時候又可以打開掌握臺打印，便利調(diào)試；r10 集合必需指定模板類型說明：便利程序閱讀，除去強制轉(zhuǎn)換代碼示例：map<string,myobject> map = new hashmap<string,myobject>r11 不要寫沒有必要的向上強制轉(zhuǎn)型；說明：沒必要寫的向上強制轉(zhuǎn)型會鋪張性能，增加代碼閱讀難度示例：

30、以下錯誤：fis = new f;inputstream is = inputstreamfis;s1記錄反常不要儲存exception.getmessage ，而要記錄exception.tostring ，一般可通過日志工具記錄完整的反常堆棧信息；說明： nullpointexception 拋出經(jīng)常常描述為空，這樣往往看不出是出了什么錯；示例：try .catch e logger.errore.tostring;s2一個方法不應(yīng)拋出太多類型的反常；說明：假如程序中需要分類處理，就將反常依據(jù)分類組織成繼承關(guān)系；假如的確有許多反常類型第一考慮用反常描述來區(qū)分，throws/exceptio

31、n子句標(biāo)明的反常最好不要超過三個；s3反常捕捉盡量不要直接catch exception ex ，應(yīng)當(dāng)把反常細分處理；說明：可以設(shè)計更合理反常處理分支s4假如多段代碼重復(fù)做同一件事情，那么在方法的劃分上可能存在問題；說明：如此段代碼各語句之間有實質(zhì)性關(guān)聯(lián)并且是完成同一件功能的，那么可考慮把此段代碼構(gòu)造成一個新的方法；s5集合中的數(shù)據(jù)假如不使用了應(yīng)當(dāng)準(zhǔn)時釋放，特殊是可重復(fù)使用的集合；說明： 由于集合儲存了對象的引用，虛擬機的垃圾收集器就不會回收；簡潔說來， 集合就是類似于list 及 map的各種容器；假如插入到容器中的對象不再使用了，應(yīng)盡快淡定器中移除；s6源程序中關(guān)系較為緊密的代碼應(yīng)盡可能相

32、鄰；說明：便于程序閱讀和查找；示例：矩形的長與寬關(guān)系較親密，放在一起；rect.length = 10;rect.width = 5;s7不要使用難懂的技巧性很高的語句，除非很有必要時；說明：高技巧語句不等于高效率的程序，實際上程序的效率關(guān)鍵在于設(shè)計與算法；s8明確方法功能，精確（而不是近似）地實現(xiàn)方法設(shè)計；一個函數(shù)僅完成一件功能，即使簡潔功能也編寫方法實現(xiàn)；說明：雖然為僅用一兩行就可完成的功能去編方法好象沒有必要，但用方法可使功能明確化，增加程序可讀性，亦可便利愛護、測試；s9應(yīng)明確規(guī)定對接口方法參數(shù)的合法性檢查應(yīng)由方法的調(diào)用者負責(zé)仍是由接口方法本身負責(zé)，缺省是由方法調(diào)用者負責(zé)；說明：對于模

33、塊間接口方法的參數(shù)的合法性檢查這一問題，往往有兩個極端現(xiàn)象，即：要么是調(diào)用者和被調(diào)用者對參數(shù)均不作合法性檢查，結(jié)果就遺漏了合法性檢查這一必要的處理過程，造成問題隱患；要么就是調(diào)用者和被調(diào)用者均對參數(shù)進行合法性檢查，這種情形雖不會造成問題，但產(chǎn)生了冗余代碼，降低了效率；s10 盡量使用java 5.0 新循環(huán)寫法；說明：代碼更加簡潔示例：arraylist<string> list = new arraylist<string> list.add.forstring str:list system.out.printlnstr;s11 使用 java 5.0 枚舉來替代以前用數(shù)字與字符串的同等目的的操作；5.0+說明： java 5.0以前沒有枚舉，大家都用數(shù)字或者字符串做枚舉同樣功能的事情示例：public enum enumdemo error,info,debugin other function ：enumdemo t = enumdemo.debug; if t = enumdemo.error ；s12 interface中定義的