好的JAVA風格（英譯）

介紹
作為一個已經工作了很多年的軟體開發人員和諮詢師，我看過大量形形色色的程式語言代碼。其中有文雅的也有醜陋的，但是不幸的是，它們中大多數代碼都是醜陋的。 我希望能夠說服你們，我的開發夥伴們，我們應該足夠的重視我們的代碼風格，尤其是那些在應用程式中提供使用者介面和其他可視化部分的代碼。在這兩部分系列的第一部分， 我會解釋為什麼我們應該關心我們的代碼外觀，然後闡述一些好的JAVA風格的一般要素。

為什麼代碼很重要
儘管JAVA是用來寫程式而不是散文， 但它仍然被用來表達思想和觀點的。而且，在調查中顯示，那些思想和觀點在實際中完成了很多事情。為編寫出好的JAVA風格而擔憂，似乎是在浪費時間， 但實際上它對我們編寫程式是很適宜的，因為它所要表達的思想和觀點是格外清晰的。

這裡提供一些理由，為什麼要使用好的JAVA代碼規範

一個軟體產品的80%的生命期是在維護（maintenance）。
幾乎沒有一個軟體在它的整個生命期裡都是被它的作者來維護的。
使用好的風格提高了軟體的可維護性。
如果原始碼和軟體產品是捆綁給客戶的，作為產品的剩餘部分，它應該有好的分包（well-packaged），足夠清晰和專業的代碼。

使用好的風格編寫代碼有以下幾點好處：

提高了代碼的可讀性，持久性，和諧性。這些都能使代碼能更容易的理解和維護。
使代碼更容易被跟蹤和調試，因為它是清晰的和持續的。
使你或另一個程式員在編寫終止時更容易再繼續下去，尤其在一個很長的時間後。
增加了代碼預排（walkthroughs）的好處， 因為能讓參入者更多的將焦點集中在代碼正在做什麼。

概要方針
使用好的JAVA風格並不困難， 但是它確實需要注意細節。下面是一些常用的概要指導方針：

使代碼更清晰和更容易讀
使代碼更持續
使用顯而易見的標識符名
邏輯地組織你的檔案和類
每個檔案只有一個類(這裡不包括一些內部類)
使用80-90個字元的最大行寬
明智的使用空格來and/or其他分隔字元
縮排上，使用空格（Space）來代替Tab

Tabs vs. 空格
在編寫代碼時，“Tabs vs. 空格” 是一個嚴謹的觀點。這裡我並不是暗示只有一個正確的方法。我支援使用空格，因為它能保證My Code在你的編輯器裡和我的編輯器裡看到的相同，反之矣然。如果你感覺使用空格來代替Tab"不是正確的", 那麼就使用Tab吧。

括弧和縮排
在編寫代碼時，縮排風格(cf., Raymond, "Indent Style")，或者放置括弧("{" 和 "}") 和一些相關聯的縮排代碼，是另一個嚴謹的觀點。象JAVA一樣，有許多C風格的語言存在。我這裡也不是暗示它們中哪一個更優先更好。在大多數本文的範例代碼中，我使用了K&R 風格，如果你不喜歡K&R風格，那麼就使用其他風格吧。

注釋
在JAVA代碼中你可以使用兩種注釋： Javadoc 注釋 (也稱為文檔注釋) 和執行注釋。 Javadoc注釋能夠被javadoc工具解壓來製造一個API文檔。執行注釋是那些解釋代碼目的和方式的注釋。在注釋你的JAVA代碼時請使用以下方針：

儘可能的使用Javadoc注釋(在類和方法上，使之能最小化).
多使用塊注釋，少使用//注釋, 除非一些特殊的情況，如變數聲明
要記住：好注釋是有協助的，壞注釋是麻煩的。

Example 1. Bad Comment Style

 // applyRotAscii() -- Apply ASCII ROT
   private void applyRotAscii(){
      try{
         int rotLength = Integer.parseInt(rotationLengthField.getText().trim()); // get rot len
         RotAscii cipher = new RotAscii(rotLength); // new cipher
         textArea.setText(cipher.transform(textArea.getText())); // transform
      }catch(Exception ex){
         /* Show exception */
         ExceptionDialog.show(this, "Invalid rotation length: ", ex); }
   }

Example 2. Good Comment Style

 /**
    * Apply the ASCII rotation cipher to the user's text. The length is retrieved
    * from the rotation length field, and the user's text is retrieved from the
    * text area.
    *
    * @author Thornton Rose
    */
   private void applyRotAscii() {
      int      rotLength = 0;  // rotation length
      RotAscii cipher = null;  // ASCII rotation cipher

      try {
         // Get rotation length field and convert to integer.

         rotLength = Integer.parseInt(rotationLengthField.getText().trim());

         // Create ASCII rotation cipher and transform the user's text with it.

         cipher = new RotAscii(rotLength);
         textArea.setText(cipher.transform(textArea.getText()));

       } catch(Exception ex) {
         // Report the exception to the user.

         ExceptionDialog.show(this, "Invalid rotation length: ", ex);
      }
   }

塊和語句
使用下面的方針來編寫塊和語句：

一行唯寫一個語句
控制語句總是使用{}這樣的括弧 (e.g., 'if').
考慮在塊的末尾使用一個注釋 (e.g., } // end if), 尤其是長的或嵌套塊
在塊的開頭放置變數的聲明語句
總記得初始設定變數
如果你是個完美主義者，靠左對齊變數名
在switch塊裡縮排case從句
在操作符後留有空白
在if, for, 或while語句中， 在括弧“（”前留有空白
在運算式中使用空白和插入語來增強可讀性
在for迴圈中的變數是個例外。 迴圈變數可能會在語句初始化部分被定義。 e.g., for (int i = 0; ...).
在塊的末尾插入注釋有助於你無意中跟蹤到被刪除的結尾括弧“}”.

Example 3. Bad Block Style.

try{
      for(int i=0;i<5;i++){
         ...
         }
      int threshold=calculateThreshold();
      float variance=(threshold*2.8)-1;
      int c=0;
      if (threshold<=15) c=calculateCoefficient();
      switch(c){
      case 1: setCeiling(c*2); break;
      case 2: setCeiling(c*3); break;
      else: freakOut();
      }
   }catch(Exception ex){ ... }

Example 4. Good Block Style.

 try {
      int   threshold  = 0;
      float variance  = 0.0;
      int   coefficient = 0;

      // Prepare 5 cycles.

      for (int i = 0; i < 5; i ++){
         prepareCycle(i);
      }

      // Calculate the threshold and variance.

      threshold = calculateThreshold();
      variance = (threshold * 2.8) - 1;

      // If the threshold is less than the maximum, calculate the coefficient.
      // Otherwise, throw an exception.

      if (threshold <= MAX_THRESHOLD) {
         coefficient = calculateCoefficient();
      } else {
         throw new RuntimeException("Threshold exceeded!");
      }

      // Set the ceiling based on the coefficient.

      switch (coefficient) {
         case 1:
            setCeiling(coefficient * 2);
            break;

         case 2:
            setCeiling(coefficient * 3);
            break;

         else:
            freakOut();
      } // end switch
   } catch(Exception ex) {
      ...
   } // end try