java編碼規(guī)范 (轉(zhuǎn))

Java 編碼規(guī)范XML:namespace prefix = o ns = "urn:schemas-microsoft-com:Office:office" />

翻譯：王士勇

（轉(zhuǎn)載請保留作者，謝謝）

1.  引言

1.1. 為什么要編碼規(guī)范

編碼規(guī)范為什么是重要的？有以下一些理由：

l  一份軟件80%的生命周期是維護期

l  任何軟件都很難說他的整個生命周期都是由他的原始作者來維護

l  編碼規(guī)范改善軟件的可讀性，使得軟件工程師充分理解新的代碼變得非常的快速。

l  如果你要把你的原碼作為產(chǎn)品發(fā)布，你需要確保他像你的其他產(chǎn)品一樣干凈并且封裝的好。

為了按照規(guī)范工作，每個人寫軟件的時候，都必須遵守編碼規(guī)范。記住，是每個人！

1.1.1.  致謝

這本書是反映的是Java Language Specification 中關(guān)于java語言編碼規(guī)范的。在這里要著重對Peter king ,Patrick Naughton,Mike DeMoney,Jonni Kanerva,Kathy Walrath,和SCOtt Hommel表示感謝。

2.  文件名

這一節(jié)列出了本書所用的大部分文件名和后綴。

2.1. 文件后綴

  .java  java 源文件后綴

  .class   java 字節(jié)碼文件后綴

2.2. 常用的文件名

  經(jīng)常使用的文件名包括以下：

  gnumakefile    首選的makefile的名字，我們使用gnumake來build我們的軟件。

  README   那些專門概述特定文件夾內(nèi)容的文件的首選的名字

3.  文件的組織

一個文件的各個部分之間應(yīng)該用空行隔開，并且應(yīng)該用一個可選的注解來標(biāo)示每個不同的部分。

文件超過2000行，是非常笨重討厭（cumbersome）的，應(yīng)該避免。

至于java 編程的正確格式的示例，請參看18頁上的”JAVA source File Example(Java 原碼文件示例)”。

3.1. Java 源碼文件

  每一個Java源碼文件都包括一個唯一的public 類或interface。當(dāng)私有的類和interface 都和這個public 類有關(guān)聯(lián)時，你可以把它們放到這個public 類的源文件中。這個public 類或interface 應(yīng)當(dāng)是這個文件的第一個類或interface 。

Java 源文件有以下的順序：

l  文件開頭注解（參見第二頁的“Beginning Comments（開頭注解）”）

l   聲明package 的語句和載入語句。

l  類和interface的聲明（參見page 3的“Class and Interface Declarations”）

3.1.1.  開頭注解

  所有的源文件都應(yīng)該以一個C語言風(fēng)格的注解開頭。這個注解應(yīng)該列出類名，版本信息，日期和版權(quán)聲明：

  /*

  *Classname

  *

  *Version information

  *

  * Date

*

 * copyright notice

 *

 */

3.1.2.  聲明包的語句和import 語句

  絕大多數(shù)java 源文件中的第一非注釋行應(yīng)該是聲明包的語句。此后，緊接著是import 語句。例如：

  package java.awt;

  import java.awt.peer.CanvASPeer;

3.1.3.  類和接口的聲明

下面的表格描述了部分的類和接口的聲明，他們應(yīng)該按照表格的順序。參看“Java Source File Example” on page 18 。

部分類/接口聲明 

注釋

類/接口文檔注解/**…*/

如何做此類注解請參看“Documentation Comments”

類或接口聲明

類/接口實現(xiàn)的注解（/*。。。*/），如果有必要的話

這個注解應(yīng)該包括任何整個類或接口范圍內(nèi)的不適合在類/接口文檔注解中出現(xiàn)的內(nèi)容。

類（靜態(tài)）變量

首先是public類變量，然后是protected類變量，然后是friendly(package level,即默認)。然后是private變量。

Instance variables(譯注：實體變量？不會翻譯了，意即普通的變量。)

首先是public,其次protected,接著package level。最后是private變量。

類的構(gòu)造函數(shù)

方法，（譯注：即類的成員函數(shù)）

這些方法應(yīng)該以功能相近為標(biāo)準(zhǔn)，組織在一塊，而不是看其作用域和可存取性。例如：一個private class 方法（譯注：意即private static method）可以被放在兩個public instance 方法（譯注：意即public method）中間。其目的是為了代碼可讀性和可理解性增加。

4.  縮進

應(yīng)該以四個空格為縮進的最小單位，縮進的精確結(jié)構(gòu)沒有被詳細定義。Tabs必須被精確指定為8個空格（而不是4個）。

4.1. 代碼行的長度

應(yīng)避免行的長度超過80個字符，因為很多的終端和工具都不支持超過80個字符。（譯注：個人認為現(xiàn)在一般都支持行超過80個字符，但是由于超過80個字符，一般要滾屏，所以盡量還是不要超過此限制。）

注意：文檔中的例子的行長度應(yīng)該更短，一般不超過70個字符。

4.2. Wrapping lines(斷行的方法)

當(dāng)一個表達式不適合一個單行時，依照以下這些一般性的原理來斷行：

l  在逗號后斷行

l  在運算操作符前斷行

l  在較高的層次斷行比在低層次斷行要好

l  把新行的表達式的開頭和上一行的表達式開頭對齊。

l  如果上一條規(guī)則導(dǎo)致代碼的混亂或者代碼超出了正常的限度。那么就僅僅以縮進8個空格來替代。

這兒有一些調(diào)用方法的斷行例子：

  someMethod(longExpression1,longExpression2,longExpression3,

    longExpression4,longExpression5);

  var=someMethod1(longExpression1,

  someMethod2(longExpression2,

  longExpression3));

  下面是兩個算術(shù)表達式的斷行的例子，第一個比第二個好，因為它的斷行發(fā)生在括號的外面，這是在高層次上的斷行。

  loNGName1 = longName2 * (longName3 + longName4 –longName5)

    + 4 * longName6;

    longName1 = longName2 * ( longName3 + longName4

    - longName5) + 4 * longName6;  //  AVOID(應(yīng)該避免這樣)

下面是兩個方法聲明的斷行的例子，第一個是規(guī)范的例子。第二個如果要使用規(guī)范的縮進的話，將會使第二和第三行縮進的非常向右。所以僅僅使用8個空格來替代。

  //規(guī)范的縮進

  someMethod ( int anArg, object anotherArg, String yetAnotherArg,

  Object andStillAnother){

  …

  }

  //以8個空格來縮進，以避免非常縱深的縮進

  private static synchronized horkingLongMethodName(int anArg,

    Object anotherArg, String yetAnotherArg,

    Object andStillAnother) {

    …

  }

  行的包裝（Line wrapping for）對if 語句一般應(yīng)該用8個空格規(guī)則，因為標(biāo)準(zhǔn)的（4個空格）縮進使得if 的主體部分非常難看明白。例如：

  //不要使用這種縮進

  if ( ( condition1 && condition2)

    || (condition3 && condition4)

  || ( condition5 && condition6)) { //差的包裝

  doSomethingAboutIt();

  }

  //以這種縮進方式代替

  if ( ( condition1 && condition2)

    || ( condition3 && conditin4 )

  || ! (condition5　&& condition6)) {

  doSomethingAboutIt();

  }

  //或者這樣使用

  if ((condition1 && condition2) || (conditin3 && condition4)

    || ! ( condition5 && condition6 )) {

  doSomethingAboutIt();

  }

  這兒有三種可接受的三元運算符的縮進格式：

  alpha = ( aLongBooleanExpression) ? beta : gamma;

  alpha = ( aLongBooleanExpression) ? beta

   : gamma;

  alpha = ( aLongBooleanExpression)

    ? beta

    : gamma;

5.  注釋（注解）

待譯。