java編碼規範（2） (轉)[@more@]

編碼規範(2):namespace prefix = o ns = "urn:schemas--com::office" />

翻譯：王士勇

（轉載請保留作者，謝謝）

比上一個版本多了很多，而且排了一下版面。希望能替換掉上一篇文章

1.  引言

1.1. 為什麼要編碼規範

編碼規範為什麼是重要的？有以下一些理由：

l  一份80%的生命週期是維護期

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

l  編碼規範改善軟體的可讀性，使得軟體工程師充分理解新的程式碼變得非常的。

l  如果你要把你的原碼作為產品釋出，你需要確保他像你的其他產品一樣乾淨並且封裝的好。

為了按照規範工作，每個人寫軟體的時候，都必須遵守編碼規範。記住，是每個人！

1.1.1.  致謝

這本書是反映的是Java Language Specification 中關於java語言編碼規範的。在這裡要著重對Peter king ,Patrick Naughton,Mike DeMoney,Jonni Kanerva,Kathy Walrath,和tt Hommel表示感謝。

2.  名

這一節列出了本書所用的大部分檔名和字尾。

2.1. 檔案字尾

  .java  java 原始檔字尾

  .class   java 位元組碼檔案字尾

2.2. 常用的檔名

  經常使用的檔名包括以下：

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

  README   那些專門概述特定資料夾內容的檔案的首選的名字

3.  檔案的組織

一個檔案的各個部分之間應該用空行隔開，並且應該用一個可選的註解來標示每個不同的部分。

檔案超過2000行，是非常笨重討厭（cumbersome）的，應該避免。

至於java 的正確格式的示例，請參看18頁上的”JAVA File Example(Java 原碼檔案示例)”。

3.1. Java 原始碼檔案

  每一個Java原始碼檔案都包括一個唯一的public 類或interface。當私有的類和interface 都和這個public 類有關聯時，你可以把它們放到這個public 類的原始檔中。這個public 類或interface 應當是這個檔案的第一個類或interface 。

Java 原始檔有以下的順序：

l  檔案開頭註解（參見第二頁的“Beginning Comments（開頭註解）”）

l   宣告package 的語句和載入語句。

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

3.1.1.  開頭註解

  所有的原始檔都應該以一個C語言風格的註解開頭。這個註解應該列出類名，版本資訊，日期和版權宣告：

  /*

  *Classname

  *

  *Version information

  *

  * Date

*

 * copyright notice

 *

 */

3.1.2.  宣告包的語句和import 語句

  絕大多數java 原始檔中的第一非註釋行應該是宣告包的語句。此後，緊接著是import 語句。例如：

  package java.awt;

  import java.awt.peer.Canveer;

3.1.3.  類和介面的宣告

下面的表格描述了部分的類和介面的宣告，他們應該按照表格的順序。參看“Java Source File Example” on page 18 。

 

部分類/介面宣告 

註釋

類/介面文件註解/**…*/

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

類或介面宣告

類/介面實現的註解（/*。。。*/），如果有必要的話

這個註解應該包括任何整個類或介面範圍內的不適合在類/介面文件註解中出現的內容。

類（靜態）變數

首先是public類變數，然後是protected類變數，然後是friendly(package level,即預設)。然後是private變數。

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

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

類的構造

方法，（譯註：即類的成員函式）

這些方法應該以功能相近為標準，組織在一塊，而不是看其作用域和可存取性。例如：一個private class 方法（譯註：意即private static method）可以被放在兩個public instance 方法（譯註：意即public method）中間。其目的是為了程式碼可讀性和可理解性增加。

4.  縮排

應該以四個空格為縮排的最小單位，縮排的精確結構沒有被詳細定義。Tabs必須被精確指定為8個空格（而不是4個）。

4.1. 程式碼行的長度

應避免行的長度超過80個字元，因為很多的終端和工具都不支援超過80個字元。（譯註：個人認為現在一般都支援行超過80個字元，但是由於超過80個字元，一般要滾屏，所以儘量還是不要超過此限制。）

注意：文件中的例子的行長度應該更短，一般不超過70個字元。

4.2. Wrap lines(斷行的方法)

當一個不適合一個單行時，依照以下這些一般性的原理來斷行：

l  在逗號後斷行

l  在運算運算子前斷行

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

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

l  如果上一條規則導致程式碼的混亂或者程式碼超出了正常的限度。那麼就僅僅以縮排8個空格來替代。

這兒有一些方法的斷行例子：

  someMethod(longExpression1,longExpression2,longExpression3,

    longExpression4,longExpression5);

  var=someMethod1(longExpression1,

  someMethod2(longExpression2,

  longExpression3));

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

  loame1 = longName2 * (longName3 + longName4 –longName5)

    + 4 * longName6;

 

    longName1 = longName2 * ( longName3 + longName4

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

下面是兩個方法宣告的斷行的例子，第一個是規範的例子。第二個如果要使用規範的縮排的話，將會使第二和第三行縮排的非常向右。所以僅僅使用8個空格來替代。

  //規範的縮排

  someMethod ( int anArg, anotherArg, String yetAnotherArg,

  Object andStillAnother){

  …

  }

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

  private static synchronized horkingLongMethodName(int anArg,

    Object anotherArg, String yetAnotherArg,

    Object andStillAnother) {

    …

  }

  行的包裝（Line wrapping for）對if 語句一般應該用8個空格規則，因為標準的（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.  註釋（註解）

待譯。