1.1 為甚麼要有程式碼慣例

1 2 3 4 5 6 7 8 9

對程式設計師來說，程式碼慣例很重要的原因有下列幾點：   * 一套軟體的生命期 80% 都是花費在維護上。 * 任何軟體都很難從頭到尾全由原來的作者來維護。 * 程式碼慣例改善軟體的可讀性，讓工程師可以更快速完整的了解新程式碼。 * 如果你將你的原始碼當作產品，你必須確定它跟你創造的其他產品包裝的 一樣好，一樣乾淨。   為了方便工作，每一個寫軟體的人都必須遵循程式碼慣例。每一個人。

1.2 致謝

1 2 3 4

這份文件反映出在 Sun MicroSystem, Inc 的 Java Language Specification 中的 Java 語言程式寫作標準。主要的貢獻者是 Peter King, Patrick Naughton , Mike DeMoney, Jonni Kanerva, Kathy Walcath 和 Scott Hommel. 這份文件是由 Scott Hommel 維護。有建議請寄到 shommel@eng.sun.com

1
2
3
4
5

  由許多小節組成的檔案應該用 "空白行" 以及 "用來辨認每個小節的選擇性註解"  分隔。
 
  超過 2000 行的檔案是很累贅的，應該避免。
 
  Java 程式適當格式的範例請參考 11.1 的 "Java 原始碼檔案範例"。

3.1 Java 原始碼檔案

1 2 3 4 5 6 7 8 9

每一個 Java 原始碼檔案都包含了一個單一的 public class/interface。 如果 private classes/interfaces 和 public class 相關，那你應該把 他們跟 public class 原始碼檔案放在一起。public 應該是這個檔案中的 第一個 calss/interface。   Java 原始碼檔案有下列順序： * 起始註解(參見 3.1.1 "起始註解") * package 和 import 敘述 * class 和 interface 宣告(參見 3.1.3 "class 和 interface 宣告")

3.1.1 起始註解

1 2 3 4 5 6 7 8 9 10 11

所有的原始碼檔案都應該以 C 語言型態的註解起始，列出類別名稱，版本資訊，日期和版權宣告。   /* * 類別名稱 * * 版本資訊 * * 日期 * * 版權宣告 */

3.1.2 package 和 import 敘述

1 2 3 4 5

大多數 Java 原始碼檔案的第一行非註解行都是 package 敘述。在這之後 跟著 import 敘述。例如：   package java.awt; import java.awt.peer.CanvasPeer;

3.1.3 class 和 interface 宣告

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30

下列表格描述了一個 class/interface 的宣告部份，以他們應該出現的順序排列。 參考 11.1 "Java 原始碼檔案範例" 來看包含註解的範例。 | class/interface | 宣告部份 備註 ----------------------------------------------------------------- 1 | class/interface 文件 參考 5.2 "文件註解" 來查看 | 註解 (/**...*/) 這註解中應該有甚麼資訊。 | 2 | class/interface 敘述 | 3 | class/interface 實作註解 這註解應該包含任何不適合做為 | (/*...*/)，如果需要的話 class/interface 文件註解的 | class/interface 廣度的資訊。 | 4 | 類別 (static) 變數 首先是 public 的類別變數，然後是 | protected，再接著是 package 層級 ( | 沒有存取修正子)，最後是 private。 | 5 | 實體變數 首先是 public，然後 protected，然後 | package(沒有存取修正子)，最後是 | private。 | 6 | 建構子 | 7 | 方法 方法應該以功能來分群，而不是以視野 | 或是存取權限分。例如 private 的 | 類別方法可以在兩個 public 實體方 | 法中間。目的是為了讓程式碼更容易閱 | 讀和了解。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

  Java 程式可以有兩種註解：實作註解和文件註解。實作註解是可以在 C++ 中看的到
  ，以 /*...*/ 和 // 分隔的。文件註解(又稱為 "doc 註解")是只有 Java 有，
  而且是用 /**...*/ 分隔的。doc 註解可以被用 javadoc 工具萃取成 HTML 檔案
  。
 
  實作註解是用來將程式碼註解掉或是說關於特定實作。doc 註解是要描述程式碼的規格
  ，必須以要讓一個手上沒有原始碼的開發者閱讀的實作不相關的觀點來寫。
 
  註解應該用來給予程式碼概觀，提供閱讀程式碼本身無法獲得的額外資訊。註解
  應該只包含與閱讀和了解這程式有關的資訊。例如這一致的套件是如何被建立，或是
  它存在於甚麼目錄都不應該被包含在註解中。
 
  對不瑣碎和無法觀察到的設計決定的討論是適當的，但是避免在程式碼中出現重
  複的資訊。冗長的註解太容易過期了。通常，避免任何程式碼改進後好像會過期
  的註解。
 
  注意：註解的頻率有時候反映出貧乏的程式碼品質。當你覺得必須強迫加入註解
  時，請考慮重寫程式碼來讓它更清楚。
 
  註解不應該被用星號或其他字元畫成的大格子包起來。
  註解不能包含特殊字元，如 form-feed 和 backspace。

5.1 實作註解格式

1	程式可以有四種實作註解的型態：區塊，單行，尾隨，行結尾。

5.1.1 區塊註解

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

區塊註解用來提供檔案，方法，資料結構和演算法的描述。區塊註解可以用在 每一個檔案起始處，或是在每個方法前面。它們也可以用在其他的位置，如在 方法內部。在函式或方法內的區塊註解應該縮排到和他們描述的碼相同的層級。 區塊註解應該在前面有一行空白行，來將它與程式碼結構分離。 /* * 這是區塊註解。 */ 區塊註解可以用 /*- 開始，這個在區塊註解起始不能重定格式時，會被當成是 縮排(1)。例如： /*- * 這裡是含有我想要 縮排(1) 去忽略的一些非常特別的格式。 * * 一 * 二 * 三 */ 注意：如果你不使用縮排(1)，那你不需要在你的程式碼中使用 /*- 或是做其它 讓步來讓某些其它人可以在你的程式碼執行縮排(1)。 參考 5.2 "文件註解"。

5.1.2 單行註解

1 2 3 4 5 6 7 8 9 10

簡短的註解可以以縮排到和隨後的碼同樣層級的單行模式出現。如果註解無法寫 成單行，那他應該遵循區塊註解格式(參見 5.1.1 小節)。單行註解前面應該有 一空白行。這是 Java 程式碼的單行註解範例： if (condition) { /* 處理這個狀況。 */ ... }

5.1.3 尾隨註解

1 2 3 4 5 6 7 8 9 10 11 12

非常短的註解可以在他們描述的程式碼同一行出現，但是應該離開足夠的距離 來讓他們與敘述分隔。如果有超過一個短註解在大區塊程式碼中出現，那他們 應該被縮排到同一個 tab 設定。 這裡是一個 Java 程式碼中的尾隨註解範例： if (a == 2) { return TRUE; /* 特別狀況 */ } else { return isPrime(a); /* 只在 a 為奇數時有作用 */ }

5.1.4 行結尾註解

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

這 // 的註解分隔子可以註解一整行或是行的一部分。他不能用在連貫的多行 文字註解中；但是他可以用在連貫的多行中來註解掉一區塊的程式碼。下列是 這三種形式的範例： if ( foo > 1) { // 做出雙空翻。 ... } else { return false; // 在這裡解釋為甚麼。 } // if (bar > 1) { // // // 做三重空翻。 // ... //} //else{ // return false; //}

5.2 文件註解

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

注意：參考 11.1 "Java 原始碼檔案範例" 來看這邊描述的註解格式範例。 進一步的細節請看包含 doc 註解標籤(@return, @param, @see) 資訊的 "How to Write Doc Comments for JavaDoc"： http://java.sun.com/products/jdk/javadoc/writingdoccomments.html 進一步的 doc 註解和 javadoc 細節，請看 javadoc 首頁： http://java.sun.com/products/jdk/javadoc/ doc 註解描述了 Java 類別, 介面, 建構子，方法，和欄位。每一個 doc 註解 都設定成放在 /**...*/ 分隔子中，每一個類別，介面或是成員都有一個註解。 這些註解應該就在在宣告的前面出現。 /** * 這個 Example 類別提供了 ... */ public class Exampke { ... 注意頂層的類別和介面並沒有縮排，而他們的成員有。這類別和介面的 doc 註解 的第一行(/**)是沒有縮排的；隨後的 doc 註解行都有 1 個縮排的空格 ( 垂直 對齊星號)。成員 (包括建構子) 的第一個 doc 註解行則有 4 個空白，以及之後的 有五個空白。 如果你需要給予不適合出現在文件中的關於類別，介面，變數，或是方法的資訊， 使用馬上接在宣告之後的區塊註解(見 5.1.1 小節)或是單行註解(見 5.1.2 小節) 來實作。例如，關於類別實作的細節應該在跟著類別敘述的區塊註解實作中，而不 是在類別的 doc 註解中。 doc 註解不應該被放在方法或是建構子的定義區塊中，因為 Java 會將文件註解 和註解後的第一個宣告關聯起來。

7.1 簡單敘述

1 2 3 4 5

每一行應該最多都只有一個敘述。例如： argv++; // 正確 argc++; // 正確 argv++; argc--; // 避免!

7.2 複合敘述

1 2 3 4 5 6 7 8

複合敘述是被括號 "{ 敘述s }" 包住的一堆敘述。參考下一小節中的例子。 * 被包住的敘述應該比複合敘述還多縮排一個層級。 * 左大括號應該在複合敘述開始那行的結尾；右大括號應該自成一行，而且應該 縮排到複合敘述起始的位置。 * 所有的敘述外面都要有大括號，即使在它們是如 if-else 或是 for 敘述的控 制架構的單行敘述時也是一樣。這會讓要加上敘述時會更容易，而不會因為忘 了加上大括號而導致意料之外的錯誤。

7.3 return 敘述

1 2 3 4 5 6 7 8

一個帶著值的 return 敘述不應該使用小括號，除非它們以某種方式讓傳回的值 更加的明顯。例如： return; return myDisk.size(); return ( size ? size : defaultSize );

7.4 if, if-else, if else-if else 敘述

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

這 if-else 類的敘述應該有下列形式： if (條件) { 敘述; } if (條件) { 敘述; } else { 敘述; } if (條件) { 敘述; } else if (條件) { 敘述; } else { 敘述; } 注意：總是在 if 敘述上使用大括號 {}。避免下列有錯誤傾向的形式： if (條件) // 避免! 這個忽略了大括號 {} ! 敘述;

7.5 for 敘述

1 2 3 4 5 6 7 8 9 10 11 12 13 14

for 敘述應該有下列形式： for( 初始化; 條件; 更新 ) { 敘述; } 而空的 for 敘述 (所有的工作都在 初始化，條件式，和更新的子句中完成的) 應該有下列形式： for ( 初始化; 條件; 更新); 當在初始化或更新子句的 for 敘述中使用逗號操作子時，應該避免超過三個變 數的複雜使用。如果有需要，在 for 迴圈之前 (對初始化子句) 或是在迴圈 的結尾 (對更新子句) 使用分開的敘述。

7.6 while 敘述

1 2 3 4 5 6 7 8 9

while 敘述應該有下列的形式： while (條件) { 敘述; } 空的 while 敘述應該有下列形式： while (條件);

7.7 do-while 敘述

1 2 3 4 5

do-while 敘述應該有下列形式： do { 敘述; } while (條件);

7.8 switch 敘述

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

switch 敘述應該有下列形式： switch (條件) { case ABC: 敘述; /* 往下穿過 */ case DEF: 敘述; break; case XYZ: 敘述; break; default: 敘述; break; } 每次有往下穿過的 case 時(不包含 break 敘述者)，在 一般會有敘述的地方 增加一個註解。這個以上面程式範例中的 /* 往下穿過 */ 註解來代表。 每一個 switch 敘述都應該包含 default case。這 default case 的 break 是多餘的，但是他可以防止如果之後加入了另一個 case 時，可能會造成的往 下穿過的錯誤。

7.9 try-catch 敘述

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

try-catch 敘述應該有下列形式： try { 敘述; } catch {ExceptionClass e} { 敘述; } try-catch 敘述也可能跟著不管 try 區塊有沒有完全成功都會執行的 finally 敘述 而有如下列所示的形式。 try { 敘述; } catch (ExceptionClass e) { 敘述; } finally { 敘述; }