Java代碼書寫規(guī)范(高手必經(jīng)之路)

1、u 符號命名規(guī)則符號名包括：模塊名，變量名，常量名，方法（函數(shù)/子程序）名,數(shù)據(jù)區(qū)名,緩沖區(qū)名等。符號命名通常應(yīng)遵循以下規(guī)則：通用規(guī)則：1、在所有命名中，都應(yīng)使用標(biāo)準(zhǔn)的英文單詞或縮寫。不得使用拼音或拼音縮寫，除非該名字描述的是中文特有的內(nèi)容，如半角、全角, 聲母、韻母等。 2、所有命名都應(yīng)遵循達(dá)意原則，即名稱應(yīng)含義清晰、明確。 3、所有命名都不易過長，應(yīng)控制在規(guī)定的最大長度以內(nèi)。 4、所有命名都應(yīng)盡量使用全稱。 5、如果命名使用縮寫，則必須對其進(jìn)行注釋和說明。 具體規(guī)范： 1、工程名 統(tǒng)一制訂。 2、文件名文件名應(yīng)與類名相同，這是java的規(guī)范3、方法名/函數(shù)名² ·方法名

2、第一個單詞小寫。² ·推薦使用動賓結(jié)構(gòu)。方法名應(yīng)清晰反映該方法的功能、用途。² ·方法名最長不得超過30個字符。 例： getCollection(); setCollection(); insertObject(); deleteObject();3、變量名必須使用有意義的變量名。推薦的類型縮寫（type）·char：ch·boolean：b·int：i·long：l·double：d·float：f 變量名最長不得超過20個字符。 4、類名² ·必須以大寫字母開頭，類名反

3、映具體含義，以清晰表達(dá)類的用途和功能為原則² ·當(dāng)名稱由多個單詞構(gòu)成時，每一個單詞的第一個字母必須大寫u 代碼書寫規(guī)范 書寫規(guī)范即在編寫代碼過程中所使用的標(biāo)準(zhǔn)格式， 主要包括空格的使用、括號的使用、縮近格式和其他一些內(nèi)容。源代碼書寫規(guī)范1在.java/.jsp的開頭應(yīng)有一段格式統(tǒng)一的說明，內(nèi)容包括： a. 文件名 (Title/FileName)； b. 創(chuàng)建人 (Author)； c. 文件創(chuàng)建時間 (Date)； d. 簡短說明文件功能、用途 (Description /Function)。 樣例：/* * 標(biāo)題:Schedule.java * 描述:用來實現(xiàn)計劃項目審

4、批 * 創(chuàng)建:2001-06-30 * 作者:趙文正 * 詳細(xì)：詳細(xì)描述計劃項目審批的細(xì)節(jié),如何根據(jù)細(xì)節(jié)功能確定方法 */2. 除非極其簡單，否則對函數(shù)應(yīng)有注釋說明。內(nèi)容包括：功能、入口/出口參數(shù)，必要時還可有備注或補充說明。 3. 每行代碼的長度推薦為80列，最長不得超過120列；折行以對齊為準(zhǔn)。 4. 在類的成員函數(shù)內(nèi)調(diào)用其他類的成員函數(shù)時，其他類的成員函數(shù)可做簡短說明。 6. 函數(shù)入口參數(shù)有缺省值時，應(yīng)注釋說明。 例: float getValue(int ID, boolean flag) /* parameter description ID: Identify No flag :

5、default = TRUE */ 7. else if 必須寫在一行。 8. 與、有關(guān)的各項規(guī)定： 、應(yīng)獨占一行。在該行內(nèi)可有注釋。 例：正確： for (i = 0; i <Line; i+) / . System.out.println("Line="+ i+” value = ”+Linesi); 不得寫做： for (i = 0; i < cb; i+) System.out.println("Line="+ i+” value = ”+Linesi); 必須另起一行，之后的代碼必須縮進(jìn)一個Tab。 與 必須在同一列上。 例：正確：

6、 if (i > 0) m = 1; n+; 不得寫做： if (i > 0) m = 1; n+; 在循環(huán)、分支之后若只有一行代碼，雖然可省略、，但不推薦這么做。若省略后可能 引起歧義，則必須加上、。例：正確： if (n = -2) n = 1; else if (n != nTemp) n = 2; else n = 3; 不得寫做： if (n = -2) n = 1; else if (n != nTemp) n = 2; else n = 3;9. 與空格有關(guān)的各項規(guī)定。 所有兩目、三目運算符的兩邊都必須有空格。在單目運算符兩端不必空格。但在 .、等運算符前后，及&am

7、p;（取地址）等運算符之后不得有空格。例：正確： int n = 0, nTemp; for (int i = nMinLine; i <= nMaxLine; i+)不得寫做： int n=0, nTemp; for ( int i=nMinLine; i<=nMaxLine; i+ ) or、while、if 等關(guān)鍵詞之后應(yīng)有1個空格，再接(，之后無空格；在結(jié)尾的)前不得有空格。例：正確： if (-2 = n)不得寫做： if(-2 = n)或 if ( -2 = n )等等。 調(diào)用函數(shù)時，(、)前后不得有空格。 類型強(qiáng)制轉(zhuǎn)換時，()前后不得有空格 10. 與縮進(jìn)有關(guān)的各項規(guī)

8、定縮進(jìn)以 Tab 為單位。1 個 Tab 為 4 個空格 下列情況，代碼縮進(jìn)一個 Tab:函數(shù)體相對函數(shù)名及、。 if、else、for、while、do 等之后的代碼。 一行之內(nèi)寫不下，折行之后的代碼，應(yīng)在合理的位置進(jìn)行折行。若有 + - * / 等運算符，則運算符應(yīng)在上一行末尾，而不應(yīng)在下一行的行首。 下列情況，不必縮進(jìn)：switch 之后的 case、default。在switch-case結(jié)構(gòu)中，case語句距離switch 語句的開始應(yīng)縮進(jìn)一個TAB，每個case的程序體距離case的開始縮進(jìn)一個TAB; 舉例：      

9、  switch (value)                        case 1:                        /* B

10、ody for case 1. */                        break;                case 2:      

11、60;                 /* Body for case 2. */                        break;     

12、60;          default:                        /* Body for default. */             

13、;           break;        所有的函數(shù)定義和函數(shù)定義的花括號都應(yīng)位于第一列； 所有成對的花括號都應(yīng)出現(xiàn)在同一列，并與相應(yīng)的控制語句同列，在對數(shù)組、類、和枚舉類型的成員初始化時，同樣遵循此規(guī)則； 對于java/jsp程序，強(qiáng)烈建議使用如下結(jié)構(gòu)： try catch(Exception ex) finally try catch (Exception e) 其他 對復(fù)雜的條件語句（分支中的語句較多），應(yīng)在每

14、個結(jié)束的花括號后加一條注釋說明是哪一個分支的結(jié)束，并在分支的開始加注釋說明進(jìn)入分支的條件；復(fù)雜的循環(huán)程序段遵循此規(guī)則； 每個語句占一行； 函數(shù)定義時，函數(shù)的返值和函數(shù)名應(yīng)在同一行。u 程序的注釋規(guī)范在項目開發(fā)過程中，對代碼的注釋十分重要，與代碼規(guī)范一樣提供良好的可讀性和易維護(hù)性，對程序中的每一個文件、類、函數(shù)以及重要的變量，都應(yīng)用相關(guān)的注釋說明他們的作者、用途和使用方法，對程序中較復(fù)雜或重要的部分應(yīng)說明它們的含義和目的，對后續(xù)添加和修改的部分應(yīng)注明修改者姓名和修改時間。 SUN提供了JavaDoc工具抽取程序中的相關(guān)注釋：以下都以SUN 的標(biāo)準(zhǔn)（即：JAVA API 規(guī)定式樣的注釋）來說明程序

15、的注釋規(guī)范，以利于根據(jù)程序的注釋用Javadoc生成API格式的java 文檔。原則：² 注釋是程序調(diào)用者和執(zhí)行者之間唯一的協(xié)議² 程序異常的注釋必須顯著的標(biāo)明注釋² 程序的注釋應(yīng)該能提供足夠的信息，根據(jù)注釋，質(zhì)量保證人員應(yīng)該能夠?qū)懗鰷y試用例Javadoc 能夠根據(jù)以下幾類文件中的注釋抽取出來生成JAVA API格式的注釋：² Java源程序，包括 源程序，接口，結(jié)構(gòu)的注釋² 包的注釋文件² 一般的注釋文件² 其它文件：包括 類文件，applet, HTML等文檔注釋的一般格式文檔的注釋通常包括兩部分。描述部分和 0 到多個

16、標(biāo)記。其格式如下例： /* * This is the description part of a doc comment * * tag Comment for the tag*/注：行的長度不超過80個字符 如果有一段以上的注釋，要使用<p>進(jìn)行分段。注釋的檢查工具SUN提供DocCheck工具，用來檢查注釋風(fēng)格和標(biāo)記的錯誤，并能提供修改建議。描述部分描述部分第一句應(yīng)該是關(guān)于該類，接口，包，成員的概括，Javadoc 工具將會copy這一句作為該部分的概括。例： /* * This is a simulation of Prof. Knuth's MIX compute

17、r. */Javadoc會抽取到Prof為止，作為概述。不過可以通過 HTML標(biāo)記 "&" or "<" 來連接連個句子。例如 /* * This is a simulation of Prof.&nbsp;Knuth's MIX computer. */或者 /* * This is a simulation of Prof.<!- -> Knuth's MIX computer.*/以下情況可以不用寫注釋，Javadoc會自動生成相應(yīng)的注釋 當(dāng)一個類的方法重載超類的方法時； 當(dāng)一個接口中的方法繼承父接

18、口中的方法時； 當(dāng)在類中實現(xiàn)該類繼承的接口的方法的時候；推薦的風(fēng)格使用<code>.</code>來標(biāo)記關(guān)鍵字或重要的名稱，如：java關(guān)鍵字，包名稱，類名稱，方法名稱，接口名稱，代碼樣例等。使用內(nèi)嵌的鏈接link來引起超連結(jié)建議使用短語代替句子，特別是在param 標(biāo)記描述的時候在描述部分中盡量是用第三人稱而不是第二人稱進(jìn)行描述，例如：      Gets the label.       (首選格式)       Get the label.    

19、60; (避免格式) 在描述是盡量是用動賓結(jié)構(gòu)      Gets the label of this button.       (首選格式)       This method gets the label of this button.       (避免格式) 避免使用拉丁語，例如：應(yīng)該用"for example"取代 "e.g.", 用"that is" 或者"to be specific&quo

20、t; 代替 "i.e."等等。標(biāo)記慣例java規(guī)定1.0版規(guī)定了一下描述標(biāo)記* author (類和接口中必須使用此標(biāo)記)* version (類和接口中必須使用此標(biāo)記) * param (只在方法和結(jié)構(gòu)中使用)* return (只在方法中使用)* exception (如 throws一樣，用來表示拋出異常)，例如： /* * throws IOException If an input or output exception occurred */ public void f() throws IOException / body * see （用來指出參考的部分）*

21、 since （開始版本）例：/* * since 1.2 */* serial (等同于serialField 或 serialData表示持續(xù)時間)* deprecated (不贊成使用 )，例：/* deprecated As of JDK 1.1, replaced by setBounds* see #setBounds(int,int,int,int)*/以上標(biāo)記如果有多個的話，通常按照字母順序列出，例如：see #field see #Constructor(Type, Type.) see #Constructor(Type id, Type id.) see #method(

22、Type, Type,.) see #method(Type id, Type, id.) see Class see Class#field see Class#Constructor(Type, Type.) see Class#Constructor(Type id, Type id) see Class#method(Type, Type,.) see Class#method(Type id, Type id,.) see package.Class see package.Class#field see package.Class#Constructor(Type, Type.)

23、see package.Class#Constructor(Type id, Type id) see package.Class#method(Type, Type,.) see package.Class#method(Type id, Type, id) see package 關(guān)于java標(biāo)記基本原則更為詳細(xì)的說明可見: Javadoc Reference page程序異常的注釋所有檢查過（catch）異常必須注釋未檢查的（RuntimeException）但調(diào)用的時候可能出現(xiàn)的異常，可適當(dāng)?shù)倪M(jìn)行注釋。包級的注釋javadoc能夠根據(jù)包的注釋文件生成包的概述文件.其過程如下 packa

24、ge.html -> package-summary.html(source file) javadoc (destination file)Copy 注釋文件中 <body> 和 </body>之間的內(nèi)容作為最為包的概述放入package-summary.html 文件. 處理注釋文件中出現(xiàn)的 see, since or link 等Javadoc 標(biāo)記Copy 第一句作為總體概述（Overview Summary）關(guān)于package.html的寫法，通常有以下2種：空的包級注釋模板，參考：Empty Template for Package-Leve

25、l Doc Comment File常用的模板格式如下：第一句應(yīng)該是關(guān)于包的概述. 如: "Provides classes and interfaces for handling text, dates, numbers and messages in a manner independent of natural languages." 說明包的內(nèi)容和目的 包的規(guī)定包括整個包的規(guī)定. 例如, java.awt 包應(yīng)該描述該包在不同操作系統(tǒng)(Windows, Solaris, Mac)下的一般規(guī)定和行為. 包括鏈接到?jīng)]出現(xiàn)在javadoc產(chǎn)生的文檔中的聲明。包括該規(guī)定的一

26、些參考 相關(guān)的文檔 包括未出現(xiàn)在規(guī)定中的申明，如樣例，向?qū)?，演示程序?類和接口的說明        Omit this section until we implement category tag 說明類和接口的邏輯分組 see 指出供參考的其他類，包，接口等內(nèi)部類的注釋關(guān)于內(nèi)部類的注釋通常如下例：/* * The method used for creating the tree. Any structural modifications * to the display of the Jtree should be done by overrid

27、ing this method. * This method adds an anonymous TreeSelectionListener to the returned JTree. * Upon receiving TreeSelectionEvents, this listener calls refresh with * the selected node as a parameter. */ public JTree makeTree(AreaInfo ai) 注釋樣例以下是SUN提供的注釋樣例，以供參考/* * Graphics is the abstract base clas

28、s for all graphics contexts * which allow an application to draw onto components realized on * various devices or onto off-screen images. * A Graphics object encapsulates the state information needed * for the various rendering operations that Java supports. This * state information includes: * <

29、ul> * <li>The Component to draw on * <li>A translation origin for rendering and clipping coordinates * <li>The current clip * <li>The current color * <li>The current font * <li>The current logical pixel operation function (XOR or Paint) * <li>The current

30、XOR alternation color * (see <a href="#setXORMode">setXORMode</a>) * </ul> * <p> * Coordinates are infinitely thin and lie between the pixels of the * output device. * Operations which draw the outline of a figure operate by traversing * along the infinitely thin pa

31、th with a pixel-sized pen that hangs * down and to the right of the anchor point on the path. * Operations which fill a figure operate by filling the interior * of the infinitely thin path. * Operations which render horizontal text render the ascending * portion of the characters entirely above the

32、baseline coordinate. * <p> * Some important points to consider are that drawing a figure that * covers a given rectangle will occupy one extra row of pixels on * the right and bottom edges compared to filling a figure that is * bounded by that same rectangle. * Also, drawing a horizontal line

33、along the same y coordinate as * the baseline of a line of text will draw the line entirely below * the text except for any descenders. * Both of these properties are due to the pen hanging down and to * the right from the path that it traverses. * <p> * All coordinates which appear as argumen

34、ts to the methods of this * Graphics object are considered relative to the translation origin * of this Graphics object prior to the invocation of the method. * All rendering operations modify only pixels which lie within the * area bounded by both the current clip of the graphics context * and the

35、extents of the Component used to create the Graphics object. * * author Sami Shaio * author Arthur van Hoff * version %I%, %G% * since JDK1.0 */public abstract class Graphics /* * Draws as much of the specified image as is currently available * with its northwest corner at the specified coordinate (

36、x, y). * This method will return immediately in all cases, even if the * entire image has not yet been scaled, dithered and converted * for the current output device. * <p> * If the current output representation is not yet complete then * the method will return false and the indicated link Ima

37、geObserver * object will be notified as the conversion process progresses. * * param img the image to be drawn * param x the x-coordinate of the northwest corner of the * destination rectangle in pixels * param y the y-coordinate of the northwest corner of the * destination rectangle in pixels * param observer the image observer to be notified as more of the * image is converted. May be <code>null</code> * return <code>true</code> if the image is completely * loaded and was painted successfully; * <code>false</code> otherwise. * see Image * see Imag