JAVA開(kāi)發(fā)編碼規(guī)范.doc

JAVA項(xiàng)目開(kāi)發(fā)編碼規(guī)范一、目的對(duì)于代碼，首要要求是它必須正確，能夠按照程序員的真實(shí)思想去運(yùn)行；第二個(gè)的要求是代碼必須清晰易懂，使別的程序員能夠容易理解代碼所進(jìn)行的實(shí)際工作。在軟件工程領(lǐng)域，源程序的風(fēng)格統(tǒng)一標(biāo)志著可維護(hù)性、可讀性，是軟件項(xiàng)目的一個(gè)重要組成部分。而目前還沒(méi)有成文的編碼風(fēng)格文檔，以致于很多時(shí)候，程序員沒(méi)有一個(gè)共同的標(biāo)準(zhǔn)可以遵守，編碼風(fēng)格各異，程序可維護(hù)性差、可讀性也很差。通過(guò)建立代碼編寫(xiě)規(guī)范，形成開(kāi)發(fā)小組編碼約定，提高程序的可靠性、可讀性、可修改性、可維護(hù)性、可繼承性和一致性，可以保證程序代碼的質(zhì)量，繼承軟件開(kāi)發(fā)成果，充分利用資源，使開(kāi)發(fā)人員之間的工作成果可以共享。 本文在參考業(yè)界已有的編碼風(fēng)格的基礎(chǔ)上，描述了一個(gè)基于 Eclipse 的項(xiàng)目風(fēng)格，力求一種統(tǒng)一的編程風(fēng)格，并從整體編碼風(fēng)格、代碼文件風(fēng)格、函數(shù)編寫(xiě)風(fēng)格、變量風(fēng)格、注釋風(fēng)格等幾個(gè)方面進(jìn)行闡述。（這些規(guī)范并不是一定要絕對(duì)遵守，但是一定要讓程序有良好的可讀性） 二、整體編碼規(guī)則1、縮進(jìn) 縮進(jìn)建議以4個(gè)空格為單位。建議在 Tools/Editor Options 中設(shè)置 Editor 頁(yè)面的Block ident為4，Tab Size 為8。預(yù)處理語(yǔ)句、全局?jǐn)?shù)據(jù)、標(biāo)題、附加說(shuō)明、函數(shù)說(shuō)明、標(biāo)號(hào)等均頂格書(shū)寫(xiě)。語(yǔ)句塊的、配對(duì)對(duì)齊，并與其前一行對(duì)齊，語(yǔ)句塊類的語(yǔ)句縮進(jìn)建議每個(gè)、單獨(dú)占一行，便于匹對(duì)。JBuilder 中的默認(rèn)方式是開(kāi)始的不是單獨(dú)一行，建議更改成上述格式（在 Project/Default Project Properties 中設(shè)置 Code Style 中選擇 Braces 為 Next line）。 2、空格 原則上變量、類、常量數(shù)據(jù)和函數(shù)在其類型，修飾名稱之間適當(dāng)空格并據(jù)情況對(duì)齊。關(guān)鍵字原則上空一格，如：if ( . 等。運(yùn)算符的空格規(guī)定如下：:、-、+、-、!、+、-（指正負(fù)號(hào)）、&（引用）等幾個(gè)運(yùn)算符兩邊不加空格（其中單目運(yùn)算符系指與操作數(shù)相連的一邊），其它運(yùn)算符（包括大多數(shù)二目運(yùn)算符和三目運(yùn)算符?:兩邊均加一空格，在作函數(shù)定義時(shí)還可據(jù)情況多空或不空格來(lái)對(duì)齊，但在函數(shù)實(shí)現(xiàn)時(shí)可以不用。,運(yùn)算符只在其后空一格，需對(duì)齊時(shí)也可不空或多空格。不論是否有括號(hào)，對(duì)語(yǔ)句行后加的注釋?xiě)?yīng)用適當(dāng)空格與語(yǔ)句隔開(kāi)并盡可能對(duì)齊。個(gè)人認(rèn)為此項(xiàng)可以依照個(gè)人習(xí)慣決定遵循與否。 3、對(duì)齊 原則上關(guān)系密切的行應(yīng)對(duì)齊，對(duì)齊包括類型、修飾、名稱、參數(shù)等各部分對(duì)齊。另每一行的長(zhǎng)度不應(yīng)超過(guò)屏幕太多，必要時(shí)適當(dāng)換行，換行時(shí)盡可能在,處或運(yùn)算符處，換行后最好以運(yùn)算符打頭，并且以下各行均以該語(yǔ)句首行縮進(jìn)，但該語(yǔ)句仍以首行的縮進(jìn)為準(zhǔn)，即如其下一行為“”應(yīng)與首行對(duì)齊。 變量定義最好通過(guò)添加空格形成對(duì)齊，同一類型的變量最好放在一起。如下例所示： int Value; int Result; int Length; DWORD Size; DWORD BufSize; 個(gè)人認(rèn)為此項(xiàng)可以依照個(gè)人習(xí)慣決定遵循與否。 4、空行 不得存在無(wú)規(guī)則的空行，比如說(shuō)連續(xù)十個(gè)空行。程序文件結(jié)構(gòu)各部分之間空兩行，若不必要也可只空一行，各函數(shù)實(shí)現(xiàn)之間一般空兩行，由于每個(gè)函數(shù)還要有函數(shù)說(shuō)明注釋，故通常只需空一行或不空，但對(duì)于沒(méi)有函數(shù)說(shuō)明的情況至少應(yīng)再空一行。對(duì)自己寫(xiě)的函數(shù)，建議也加上“/-”做分隔。函數(shù)內(nèi)部數(shù)據(jù)與代碼之間應(yīng)空至少一行，代碼中適當(dāng)處應(yīng)以空行空開(kāi)，建議在代碼中出現(xiàn)變量聲明時(shí)，在其前空一行。類中四個(gè)“p”之間至少空一行，在其中的數(shù)據(jù)與函數(shù)之間也應(yīng)空行。 5、注釋 注釋是軟件可讀性的具體體現(xiàn)。程序注釋量一般占程序編碼量的20%，軟件工程要求不少于20%。程序注釋不能用抽象的語(yǔ)言，類似于處理、循環(huán)這樣的計(jì)算機(jī)抽象語(yǔ)言，要精確表達(dá)出程序的處理說(shuō)明。例如：計(jì)算凈需求、計(jì)算第一道工序的加工工時(shí)等。避免每行程序都使用注釋，可以在一段程序的前面加一段注釋，具有明確的處理邏輯。 注釋必不可少，但也不應(yīng)過(guò)多，不要被動(dòng)的為寫(xiě)注釋而寫(xiě)注釋。以下是四種必要的注釋： A. 標(biāo)題、附加說(shuō)明。 B. 函數(shù)、類等的說(shuō)明。對(duì)幾乎每個(gè)函數(shù)都應(yīng)有適當(dāng)?shù)恼f(shuō)明，通常加在函數(shù)實(shí)現(xiàn)之前，在沒(méi)有函數(shù)實(shí)現(xiàn)部分的情況下則加在函數(shù)原型前，其內(nèi)容主要是函數(shù)的功能、目的、算法等說(shuō)明，參數(shù)說(shuō)明、返回值說(shuō)明等，必要時(shí)還要有一些如特別的軟硬件要求等說(shuō)明。公用函數(shù)、公用類的聲明必須由注解說(shuō)明其使用方法和設(shè)計(jì)思路，當(dāng)然選擇恰當(dāng)?shù)拿袷侥軌驇椭惆咽虑榻忉尩酶宄?C. 在代碼不明晰或不可移植處必須有一定的說(shuō)明。 D. 及少量的其它注釋，如自定義變量的注釋、代碼書(shū)寫(xiě)時(shí)間等。 注釋有塊注釋和行注釋兩種，分別是指：/*/和/建議對(duì)A用塊注釋，D用行注釋，B、C則視情況而定，但應(yīng)統(tǒng)一，至少在一個(gè)單元中B類注釋形式應(yīng)統(tǒng)一。具體對(duì)不同文件、結(jié)構(gòu)的注釋會(huì)在后面詳細(xì)說(shuō)明。 6、代碼長(zhǎng)度 對(duì)于每一個(gè)函數(shù)建議盡可能控制其代碼長(zhǎng)度為53行左右，超過(guò)53行的代碼要重新考慮將其拆分為兩個(gè)或兩個(gè)以上的函數(shù)。函數(shù)拆分規(guī)則應(yīng)該一不破壞原有算法為基礎(chǔ)，同時(shí)拆分出來(lái)的部分應(yīng)該是可以重復(fù)利用的。對(duì)于在多個(gè)模塊或者窗體中都要用到的重復(fù)性代碼，完全可以將起獨(dú)立成為一個(gè)具備公用性質(zhì)的函數(shù)，放置于一個(gè)公用模塊中。 7、頁(yè)寬 頁(yè)寬應(yīng)該設(shè)置為80字符。源代碼一般不會(huì)超過(guò)這個(gè)寬度, 并導(dǎo)致無(wú)法完整顯示, 但這一設(shè)置也可以靈活調(diào)整. 在任何情況下, 超長(zhǎng)的語(yǔ)句應(yīng)該在一個(gè)逗號(hào)或者一個(gè)操作符后折行. 一條語(yǔ)句折行后, 應(yīng)該比原來(lái)的語(yǔ)句再縮進(jìn)2個(gè)字符. 8、行數(shù) 一般的集成編程環(huán)境下，每屏大概只能顯示不超過(guò)50行的程序，所以這個(gè)函數(shù)大概要5-6屏顯示，在某些環(huán)境下要8屏左右才能顯示完。這樣一來(lái)，無(wú)論是讀程序還是修改程序，都會(huì)有困難。因此建議把完成比較獨(dú)立功能的程序塊抽出，單獨(dú)成為一個(gè)函數(shù)。把完成相同或相近功能的程序塊抽出，獨(dú)立為一個(gè)子函數(shù)?？梢园l(fā)現(xiàn)，越是上層的函數(shù)越簡(jiǎn)單，就是調(diào)用幾個(gè)子函數(shù)，越是底層的函數(shù)完成的越是具體的工作。這是好程序的一個(gè)標(biāo)志。這樣，我們就可以在較上層函數(shù)里容易控制整個(gè)程序的邏輯，而在底層的函數(shù)里專注于某方面的功能的實(shí)現(xiàn)了。三、命名規(guī)范定義這個(gè)規(guī)范的目的是讓項(xiàng)目中所有的文檔都看起來(lái)像一個(gè)人寫(xiě)的，增加可讀性，減少項(xiàng)目組中因?yàn)閾Q人而帶來(lái)的損失。（這些規(guī)范并不是一定要絕對(duì)遵守，但是一定要讓程序有良好的可讀性）1. 類名必須由大寫(xiě)字母開(kāi)頭而單詞中的其他字母均為小寫(xiě)。但是由于Java面向?qū)ο缶幊痰奶匦?，每一名Java程序員都可以編寫(xiě)屬于自己的Java包，為了保障每個(gè) Java包命名的唯一性，在最新的Java編程規(guī)范中，要求程序員在自己定義的包的名稱之前加上唯一的前綴。由于互聯(lián)網(wǎng)上的域名稱是不會(huì)重復(fù)的，所以程序員一般采用自己在互聯(lián)網(wǎng)上的域名稱作為自己程序包的唯一前綴。例如： net.frontfree.javagroup2. 屬性（成員變量）、方法、對(duì)象變量以及所有標(biāo)識(shí)符（如形式參數(shù)、實(shí)際參數(shù)、局部變量）的首字母應(yīng)小寫(xiě)，其中包含的所有單詞都應(yīng)緊靠在一起，而且大寫(xiě)中間單詞的首字母。屬性或方法名：thisIsMethodOrFieldName對(duì)象變量：thisIsAClassVariable3. Java 包（Package）屬于一種特殊情況，它們?nèi)际切?xiě)字母，即便中間的單詞亦是如此。對(duì)于全局包，將你的 Internet 域名反轉(zhuǎn)并接上包名，例如：.usst.dingyuewei.package另外，package 行要在 import 行之前，import 中標(biāo)準(zhǔn)的包名要在本地的包名之前，而且按照字母順序排列。如果 import 行中包含了同一個(gè)包中的不同子目錄，則應(yīng)該用 * 來(lái)處理。例如package .stats;import java.io.*;import java.util.Observable;import hotlava.util.Application;這里 java.io.* 是用來(lái)代替InputStream and OutputStream 的。4. 接口（Interface）：采用完整的英文描述符說(shuō)明接口封裝，所有單詞的第一個(gè)字母大寫(xiě)。習(xí)慣上，名字后面加上后綴 able， ible 或者 er。例如：Contactable，Prompter。5. 組件（Component）使用完整的英文描述來(lái)說(shuō)明組件的用途，末端應(yīng)接上組件類型。例如：okButton，customerList，fileMenu。6. 類中常用方法的命名：類的獲取方法（一般具有返回值）一般要求被方法名使用被訪問(wèn)字段名，前面加上前綴get，如getFirstName(), getLastName()。類的布爾型的判斷方法一般要求方法名使用單詞 is 做前綴，如isPersistent(),isString()?；蛘呤褂镁哂羞壿嬕饬x的單詞，例如equal 或equals類的設(shè)置方法（一般返回類型為void）：被訪問(wèn)字段名的前面加上前綴 set，如setFirstName(),setLastName()，setWarpSpeed()。類的普通方法一般采用完整的英文描述說(shuō)明成員方法功能，第一個(gè)單詞盡可能采用一個(gè)生動(dòng)的動(dòng)詞，第一個(gè)字母小寫(xiě)，如 openFile(), addAccount()。構(gòu)造方法應(yīng)該用遞增的方式寫(xiě)（比如：參數(shù)多的寫(xiě)在后面）。例如：public CounterSet()public CounterSet(int size) this.size = size;toString 方法：一般情況下，每一個(gè)類都應(yīng)該定義 toString 方法，其格式為 ：public String toString() 一般應(yīng)考慮置入一個(gè)main()方法，其中包含用于測(cè)試那個(gè)類的代碼，如果包含了main() 方法, 那么它應(yīng)該寫(xiě)在類的底部。7. 靜態(tài)常量字段（static final）一般全部采用大寫(xiě)字母，單詞之間用下劃線分隔（也有特例，如Java 類庫(kù)中關(guān)于顏色的常數(shù)沒(méi)有嚴(yán)格地全部使用大寫(xiě)字母）。如MIN_BALANCE,DEFAULT_DATE。8. 循環(huán)計(jì)數(shù)變量通常采用字母 i，j，k 或者 counter。而數(shù)組應(yīng)該總是用下面的方式來(lái)命名：objectType或 byte buffer。四、注釋約定1. 類的整體注釋：遵循JavaDoc的規(guī)范，在每一個(gè)源文件的開(kāi)頭注明該CLASS的作用, 作簡(jiǎn)要說(shuō)明, 并寫(xiě)上源文件的作者, 編寫(xiě)日期。如果是修改別人編寫(xiě)的源文件，要在修改信息上注明修改者和修改日期。例如：/* （#）:CLASSNAME.java* description: Description of this java* author: PROGRAMMERS NAME YYYY/MM/DD* version: Version No.* modify:* Copyright: 版權(quán)由 擁有*/2. 類中方法的注釋：遵循JavaDoc的規(guī)范，在每個(gè)方法的前部用塊注釋的方法描述此方法的作用，以及傳入，傳出參數(shù)的類型和作用，以及需要捕獲的錯(cuò)誤。例如：/* 方法的描述*param 參數(shù)的描述*return 返回類型的描述*exception 出錯(cuò)信息的描述*/3. 行注釋：使用 /的注釋方法來(lái)注釋需要表明的內(nèi)容。并且把注釋的內(nèi)容放在需要注釋的代碼的前面一行或同一行。4. 塊注釋：使用/*和*/注釋的方法來(lái)注釋需要表明的內(nèi)容。并且把注釋的內(nèi)容放在需要注釋的代碼的前面。5. 注釋哪些部分：類的目的（即類所完成的功能）、設(shè)置接口的目的以及應(yīng)如何被使用、成員方法注釋（對(duì)于設(shè)置與獲取成員方法，在成員變量已有說(shuō)明的情況下，可以不加注釋；普通成員方法要求說(shuō)明完成什么功能，參數(shù)含義是什么？返回什么？）、普通成員方法內(nèi)部注釋（控制結(jié)構(gòu)、代碼做了些什么以及為什么這樣做，處理順序等）、實(shí)參和形參的含義以及其他任何約束或前提條件、字段或?qū)傩悦枋?。而?duì)于局部變量，如無(wú)特別意義的情況下不加注釋。五、其它約定1. JSP文件命名采用完整的英文描述說(shuō)明JSP所完成的功能，盡可能包括一個(gè)生動(dòng)的動(dòng)詞，第一個(gè)字母小寫(xiě)，如：viewMessage.jsp、editUser.jsp 或者forumChooser.jsp 等。2. Servlet 類命名一般對(duì)應(yīng)于所服務(wù)的對(duì)象加后綴Service 來(lái)命名，如：UserService，TradeService 等。3. 使用 StringBuffer 對(duì)象：在處理 String 的時(shí)候要盡量使用 StringBuffer 類，StringBuffer 類是構(gòu)成 String 類的基礎(chǔ)。String 類將 StringBuffer 類封裝了起來(lái)，（以花費(fèi)更多時(shí)間為代價(jià)）為開(kāi)發(fā)人員提供了一個(gè)安全的接口。當(dāng)我們?cè)跇?gòu)造字符串的時(shí)候，我們應(yīng)該用 StringBuffer 來(lái)實(shí)現(xiàn)大部分的工作，當(dāng)工作完成后將StringBuffer 對(duì)象再轉(zhuǎn)換為需要的 String 對(duì)象。比如：如果有一個(gè)字符串必須不斷地在其后添加許多字符來(lái)完成構(gòu)造，那么我們應(yīng)該使用 StringBuffer 對(duì)象和它的append() 方法。如果我們用 String 對(duì)象代替 StringBuffer 對(duì)象的話，會(huì)花費(fèi)許多不必要的創(chuàng)建和釋放對(duì)象的 CPU 時(shí)間。4. 避免太多的使用 synchronized 關(guān)鍵字：避免不必要的使用關(guān)鍵字 synchronized，應(yīng)該在必要的時(shí)候再使用它，這是一個(gè)避免死鎖的好方法。 必須使用時(shí)，也盡量控制范圍，最好在塊級(jí)控制。5. 避免使用 java.util.Vector 類：因?yàn)閂ector 是 is synchronized.，所以使用java.