JAVA編碼規(guī)約

1、JAVA編碼規(guī)約1、 介紹1 1為什么要有代碼慣例代碼慣例之所以重要有以下幾點(diǎn)原因： 軟件壽命價(jià)值的80%是維護(hù)。幾乎沒有軟件在整個(gè)使用過程中都有由原作者維護(hù)。代碼慣例增加了軟件包的可讀性，使工程師們能更快、更完整地理解新軟件。如果你想把你的原始代碼變成產(chǎn)品，你需要確認(rèn)它是否和你生產(chǎn)的其它產(chǎn)品一樣有好的包裝。1 2確認(rèn)這個(gè)文件在SUN 公司的JAVA語言說明書中反映了JAVA語言編碼標(biāo)準(zhǔn)。這方面規(guī)定主要來自Peter King,Patrick Naughton,Jonni Kanerva,and Scott Hommel.關(guān)于這個(gè)文檔的改寫、修改或再分配的問題，請(qǐng)看版權(quán)公告。對(duì)于這個(gè)文檔的建議

2、請(qǐng)發(fā)貼自alans2-文件名這一節(jié)列舉了常用的文件后綴與名稱。21文件后綴JAVA使用以下后綴：文件種類后綴JAVA source.javaJAVA bytecode.class22普通文檔名稱通常用的文檔名稱文檔名稱使用GNUmakefilemakefile最恰當(dāng)?shù)拿?。我們使用gnumake制造我們的軟件。Readme概括特定目錄內(nèi)容的文檔的最恰當(dāng)名稱。3. 文件的組織結(jié)構(gòu)一個(gè)文件應(yīng)當(dāng)由多個(gè)被分隔的段組成，并由空行和可選擇注釋來識(shí)別。超過2000行的文件由于冗長而應(yīng)當(dāng)避免。Java程序的正確格式可參看第19頁的范例“Java源文件范例”。31 Java源文件每一個(gè)Java源文件包含一個(gè)單一

3、的公共類或界面。當(dāng)私有類或界面與一個(gè)公共類發(fā)生聯(lián)系時(shí)，你可以將它們以一個(gè)公共類放入同一個(gè)源文件。公共類應(yīng)當(dāng)是文件中的第一類或界面。Java源文件有如下次序：起始注釋（參看第4頁“起始注釋”）組件和導(dǎo)入語句類和界面聲明（參看第4頁“類和界面聲明”）311 起始注釋所有源文件應(yīng)當(dāng)以C格式注釋開始，并列出類名，版本信息，時(shí)間和版權(quán)說明：/*類名*版本信息*時(shí)間*版權(quán)說明*/312 組件和導(dǎo)入語句對(duì)于大部分Java源文件而言，第一個(gè)無注釋行是組件語句。之后，緊跟著是導(dǎo)入語句。舉例如下：組件 java.awt;導(dǎo)入 java.awt.peer.CanvasPeer注釋：對(duì)于唯一的組件名，第一部分總是小寫

4、的ASCII碼格式的文本文件，并且是最高級(jí)別的域名之一。目前可用com,edu,gov,mil,net或ISO3166標(biāo)準(zhǔn)（1981）中規(guī)定的用于識(shí)別國家的英文兩個(gè)字母的模式。313 類和界面聲明下表按出現(xiàn)的先后順序描述了一個(gè)類或界面說明的各部分。參見第19頁“java源文件范例”中一個(gè)包含注釋的示例。類/界面聲明的各部分注釋1類/界面文檔注釋(/*/)參看第9頁“文擋注釋”中注釋的具體內(nèi)容2類或界面語句3類/界面補(bǔ)充注釋（/*/），如果必要的話這一注釋應(yīng)包含任一類寬或界面寬度的信息，它不適合于類/界面文檔注釋。4類（靜態(tài)的）變量首先是公共類變量，其次是保護(hù)類，然后是組件級(jí)（無訪問修改權(quán)），最

5、后是私有類。5實(shí)例變量首先是公共類，其次是保護(hù)類，然后是組建級(jí)（無訪問修改權(quán)），最后是私有類。6構(gòu)成7過程這些過程應(yīng)當(dāng)以功能而非作用域和可訪問性來分組。舉例說明，一個(gè)私有類變量過程可在兩個(gè)公共實(shí)例過程中。其目的是使讀和理解代碼更為容易。4、 縮進(jìn)格式四個(gè)空格作為一個(gè)縮進(jìn)單位。確切的縮進(jìn)格式結(jié)構(gòu)（空格符與制表符）未被規(guī)范。表格的設(shè)置必須在每8個(gè)空格后（而非4個(gè)）。41 行的長度由于難于被大多數(shù)終端和工具進(jìn)行處理，應(yīng)當(dāng)避免一行超過80個(gè)字符。注釋：在文檔中所列舉的范例其行的長度應(yīng)稍短些，一般不超過70個(gè)字符。42 繞回行當(dāng)表達(dá)式一行無法寫完時(shí)，使用以下一般規(guī)則進(jìn)行中斷：在逗號(hào)后中斷。在一個(gè)運(yùn)算符前

6、中斷。優(yōu)先選擇高級(jí)中斷指令。新行起始表達(dá)式的位置應(yīng)與舊行表達(dá)式的位置對(duì)齊。如果上述規(guī)則導(dǎo)致代碼混亂或編碼時(shí)頂?shù)搅擞疫吔?，?個(gè)空格代替。以下是幾個(gè)中斷程序的調(diào)用范例：someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3);以下是兩個(gè)關(guān)于中斷算術(shù)表達(dá)式的例子。第一個(gè)例子由于中斷發(fā)生在插入表達(dá)式以外，因而

7、選擇了高級(jí)中斷指令。longName1 = longName2 * (longName3 + longName4 longName5) + 4 * longname6; / PREFERlongName1 = longName2 * (longName3 + longName4longName5) + 4 * longname6; / AVOID 以下是兩個(gè)關(guān)于縮進(jìn)程序的說明。第一個(gè)例子是常規(guī)情況。第二個(gè)例子如果采用常規(guī)縮進(jìn)方式，第二和第三行在換行時(shí)必然頂至最右，取而代之應(yīng)空8格。/常規(guī)的縮進(jìn)方式someMethod(int anArg, Object anotherArg, String y

8、etAnotherArg, Object andStillAnother) 。/縮8個(gè)空格以避免更深的鎖進(jìn)private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) 。由于常規(guī)的4空格縮進(jìn)方式使得體看上去過于復(fù)雜，對(duì)于語句的繞回行我們一般采用8空格縮進(jìn)方式。舉例如下：/不要使用這種縮進(jìn)方式if (condition1 & condition2) (condition3 & condition4) !(co

9、ndition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS/取而帶之使用這種縮進(jìn)方式if (condition1 & condition2) (condition3 & condition4) !(condition5 &condition6) doSomethingAboutIt();/或使用這種方式if (condition1 & condition2) (condition3 & condition4) !(condition5 &condition6) doSomethingA

10、boutIt();以下有三種可行的方式來格式化三元表達(dá)式：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongbooleanExpression) ? beta :gamma;alpha = (aLongBooleanExpression) ? beta : gamma;5 注釋JAVA 程序可以有二種類型的注釋：執(zhí)行注解和文件注釋。執(zhí)行注釋是建立在C+之上的，以/*/為分隔符的注釋；文件注釋（即通常所說的doc comment）是一種純JAVA 注釋，以/*/為分隔符。Doc comment (文件注釋)能夠通過JAVA

11、DOCA工具被摘錄成HEML文件。執(zhí)行注釋是指為代碼注解釋，或?yàn)樘貏e執(zhí)行注解釋。Doc 注釋旨在從一個(gè)自由執(zhí)行的程序描述代碼的規(guī)范，對(duì)于軟件開發(fā)者來說，手邊不再需要源代碼就可以閱讀。注釋通常用于對(duì)代碼做總的描述，同時(shí)提供附加的信息，這從代碼本身來看是不容易得到的。其包含的信息只與閱讀、理解該程序有關(guān)，例如：一個(gè)相應(yīng)組件如何被建立的信息或駐足在何地址錄下的信息都將被包含在一個(gè)注解中。對(duì)于重要的、非顯而易見的設(shè)計(jì)決定的討論是適當(dāng)?shù)?，但是?yīng)該避免重復(fù)信息在代碼中出現(xiàn)。而對(duì)于多余注釋，則很容易成為過時(shí)的?？偟恼f來，應(yīng)當(dāng)避免把過時(shí)的注釋做為編碼的進(jìn)展。注意：經(jīng)常出現(xiàn)的注釋有時(shí)反映編碼質(zhì)量的低下。當(dāng)你覺得

12、不得不添加注釋時(shí)，建議你最好重新編寫，使得編碼更清晰。注釋不能以星號(hào)或是其它字符為標(biāo)識(shí)被附在一個(gè)大的邏輯單元內(nèi)。注釋也不能包括特殊字符例如form-feed和backspace。5.1 執(zhí)行注釋的格式程序可以有四種注釋風(fēng)格：塊、單行、跟蹤和行尾。5.1.1塊注釋塊注釋用于提供文件的描述、方法、數(shù)據(jù)結(jié)構(gòu)和運(yùn)算法則。塊注釋用于每個(gè)文件的開始和方法之前。也可以用在其他地方，比如用在方法中。在一個(gè)函數(shù)或方法中的塊注釋，應(yīng)和他們描述的代碼排列到同一級(jí)別上。塊注釋應(yīng)設(shè)置在一個(gè)空行的開始。/* * Here is a block comment. */塊注釋以/*開始，并且單獨(dú)領(lǐng)導(dǎo)一行，縮進(jìn)一格作為塊注釋的

13、開始，這已經(jīng)是約定俗成的，不需要另外重新定義格式。例如：/*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */Note: If you dont use indent(1), you dont have to use /*- in your code or make any other concessions to the possibility that someone else might run i

14、ndent(1) on your code.5.1.2 單行注釋簡短的注釋可以出現(xiàn)在單行上，和其描述的代碼在同一級(jí)別上。單行注釋應(yīng)遵循塊注釋的格式。單行注釋應(yīng)單起一行。例如：if (condition) /* Handle the condition. */ .5.1.3 跟蹤注釋簡短的注釋可以和其所描述的代碼放到同一行上。但應(yīng)和代碼保持足夠遠(yuǎn)的空間。如果不只一個(gè)簡短的注釋出現(xiàn)在大塊的代碼段中，它們應(yīng)有同樣的tab設(shè)置。例如：if (a = 2) return TRUE; /* special case */ else return isPrime(a); /* works only for

15、odd a */5.1.4 行尾注釋/注釋界定符能注釋一整行或行的一部分，它不應(yīng)該用在連續(xù)的多行文本注釋中。然而，它可以用在連續(xù)的多行代碼段中。例如：if (foo 1) / Do a double-flip. .else return false; / Explain why here./if (bar 1) / / Do a triple-flip./ ./else / return false;/5.2 文件注釋文件注釋描述Java類、界面、容器、方法和域，每一個(gè)文件注釋都放在注釋界定符/*.*/之間。注釋應(yīng)在聲明之前。/* * The Example class provides .

16、*/public class Example .注意頂級(jí)類和界面不縮進(jìn)，子類和界面則要縮進(jìn)。類和界面的第一行文件注釋不縮進(jìn)，后面的注釋行有有一個(gè)空格的縮進(jìn)。子類，包括容器，有4個(gè)空格和五個(gè)空格的縮進(jìn)。如果你需要給出關(guān)于類、界面, 變量, 或方法的信息，這些信息以文件的方式給出是不適當(dāng)?shù)?，那麼你可以直接的在聲明之后使用執(zhí)行塊注釋或單行注釋。例如，類執(zhí)行的細(xì)節(jié)信息應(yīng)放進(jìn)執(zhí)行塊注釋中，并跟在類語句之后，而不是放在類的文件注釋中。文件注釋不應(yīng)該放到方法或容器的定義塊中，因?yàn)镴ava將文件注釋和第一個(gè)注釋之后的聲明發(fā)生聯(lián)系。6、聲明6.1每一行的數(shù)量每一行中都應(yīng)有相應(yīng)的注釋，換句話說int level;

17、 / indentation levelint size; / size of table這種形式是首選的，而不是int level, size;不要將不同類型的放入同一行中，例如：int foo, fooarray; /WRONG!注意：上面的例子中在類型和標(biāo)識(shí)之間有一個(gè)空格，另一個(gè)可接受的方法是用tab，例如：intlevel; / indentation levelintsize; / size of tableObjectcurrentEntry; / currently selected table entry6.2 初始化被聲明的局部變量，應(yīng)設(shè)法將其初始化。6.3 布置聲明應(yīng)放在塊

18、的開始。不要一直到用到第一個(gè)變量的時(shí)候才開始聲明，那將使粗心的程序員迷惑，并且妨礙代碼的輕便性。void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 在Java中，for循環(huán)中的指針可以在for語句中聲明，例如for (int i = 0; i = 0) ? x : -x;10.5.4特殊注釋用XXX作為注釋信息來試圖標(biāo)記一些事情，那是不切實(shí)際的。用FIXME標(biāo)記某些事情，那也是不切實(shí)際的。11代碼例子11.1 JAVA源文

19、件例子下面的例子顯示了如何格式化一個(gè)包含單一公用類的JAVA源文件。同樣的界面也被格式化，更多的信息請(qǐng)參見Class and Interface Declarations on page 4 and Documentation Comments on page 9/* * (#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. * All rights reserved. *

20、 * This software is the confidential and proprietary information of Sun * Microsystems, Inc. (Confidential Information). You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. */package java.blah;import java.blah.blahdy.BlahBlah;/* * Class description goes here. * * version 1.82 18 Mar 1999 * author Firstname Lastname */public class Blah extends SomeClass /* A class implementation comment can go here. */ /* classVar1 documentation comment */ public static int