Code Conventions for the Java Programming Language

it quote from http://java.sun.com/docs/codeconv/CodeConventions.pdf

Some chapter is very useful to me.
I am very appreciate a man who called "良格葛", translated this Document.

Chapter 9:

 命名慣例讓程式更容易被理解和閱讀。他們也可以給予關於識別子功能的
 資訊 -- 例如，是否為常數，套件，或是類別 -- 這可以在瞭解程式碼時很有
 幫助。

變數型態　|  命名規則                           範例n-------------------------------------------------------------------------
套件　　　|  獨一無二的套件名稱的前置字都 　　　com.sun.eng
　　　　　|  是使用所有都是小寫的 ASCII
　　　　　|  字母而且應該是頂層 DN 名稱，　　　com.apple.quicktime.v2
　　　　　|  目前有 com, edu, gov, mil,
　　　　　|  net, org 或是 1981 年 ISO 　　　edu.cmu.cs.bovik.cheese
　　　　　|  標準 3166 中用來辨識國家的兩
　　　　　|  字母碼。
　　　　　|
　　　　　|  接下來的套件名稱元件根據組織
　　　　　|  擁有的內部命名慣例而不同。這
　　　　　|  種慣例會指定某種被分隔的目錄
　　　　　|  名稱元件，部門，計畫，機器，
　　　　　|  或是登入名稱。
　　　　　|
　　　　　|
類別　　　|  類別名稱應該是名詞，由每個內　　　class Raster;
　　　　　|  部單字開頭字母皆為大寫的混和　　　class ImageSprite;
　　　　　|  字組成。試著讓你的類別名稱是
　　　　　|  個很簡單的敘述。使用整個字 --
　　　　　|  避免用頭字語或是縮寫 (除非縮
　　　　　|  寫比長字的形式被用的更廣泛。
　　　　　|  例如 URL 或 HTML)。
　　　　　|
　　　　　|
介面　　　|  介面名稱應該像類別名稱的大寫　　interface RasterDelegate;
　　　　　|  法一樣。　　　　　　　　　　　　interface Storing;
　　　　　|
　　　　　|
方法　　　|  方法應該為動詞，混和第一個字　　run();
　　　　　|  母小寫和內部單字的第一個字母　　runFast();
　　　　　|  大寫的狀況。　　　　　　　　　　getBackground();
　　　　　|
　　　　　|
變數　　　|  除了變數之外，所有的實體，類　　int　　i;
　　　　　|  別，以及類別常數都是第一個字　　char　　c;
　　　　　|  母為小寫的混和狀況。內部單字　　float　　myWidth;
　　　　　|  則以大寫開頭。變數字不應以底
　　　　　|  線 _ 或是錢字號 $ 字元起始，
　　　　　|  就算這兩個都是被 Java 允許的。
　　　　　|
　　　　　|  變數名稱應該是短但仍有意義的
　　　　　|  。這變數名稱的選擇應該是幫助
　　　　　|  記憶的 -- 也就是說設計來讓不
　　　　　|  經意的觀察者都知道它使用的意
　　　　　|  圖。除了暫時使用後就被 "丟開"
　　　　　|  的變數名稱之外，應該避免使用
　　　　　|  單字元的變數。普遍使用的暫時
　　　　　|  變數名稱為用在整數的 i, j,
　　　　　|   k, m, 和 n 以及用在字元的 e。
　　　　　|
　　　　　|
常數　　　|  宣告類別常數的變數名稱以及　　　static final int MIN_WIDTH = 4;
　　　　　|  ANSI 常數的變數名稱應該是以　　static final int MAX_WIDTH = 999;
　　　　　|  ("_") 底線分隔的全大寫字。(　　static final int GET_THE_CPU = 1;
　　　　　|  為了易於除錯，應該避免 ANSI
　　　　　|  常數。)
　　　　　|

Chapter 10:

10.1 提供實體變數和類別變數的權限

1 2 3 4 5 6 7

沒有好理由的話，不要讓任何的實體變數或是類別變數是 public 的。通常 ，實體變數不需要被直接的設定或是獲得 -- 通常是作為方法呼叫的邊際效 應。 一個適當的 public 實體變數的例子是當這個類別是一個沒有行為的基本的 資料結構時。換句話說，如果你可能會使用 struct 來代替類別的話 (如果 Java 支援 struct 的話) ，那讓類別的實體變數是 public 就是適當的。

10.2 引用類別變數和方法

1 2 3 4 5 6

避免使用物件來存取類別(static)變數和方法。使用類別名稱來代替。例如 ： classMethod(); // OK AClass.classMethod(); // OK anObject.classMethod(); // 避免!

10.3 常數

1 2	會出現在 for 迴圈中當作計數值的數值常數 (直譯 字) ，除了 -1，0，和 1 之外，不應該直接編寫。

10.4 變數指定

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

避免在單一敘述中指定好幾個變數為同一個值。那會不容易閱讀。例如： fooBar.fChar = barFoo.lchar = 'c'; // 避免! 不要在可能很容易會跟相等運算子搞混的地方使用指定運算子。例如： if (c++ = d++) { // 避免！ ( Java 不允許) ... } 應該寫成 if ((c++ = d++) != 0) { ... } 不要為了改善執行效率而使用嵌入式的指定。這是編譯器的工作。例如： d = ( a = b + c) + r; // 避免! 應該寫成 a = b + c; d = a + r;

10.5 雜項慣例

10.5.1 小括號

1 2 3 4 5 6

在表示式中包含了混和的操作子時，使用大量的小括號來避免優先權的問題是 一個不錯的作法。即使操作子的優先權對你來說看來很清楚，對別人來說可能 不是如此 -- 你不應該假設其他的程式設計師對優先權的瞭解跟你一樣好。 if (a == b && c == d) // 避免! if ((a == b) && (c == d)) // 使用

10.5.2 傳回值

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

試著讓你程式的架構符合意圖。例如： if (booleanExpression) { return true; } else { return false; } 應該以下列取代 return booleanExpression; 相同的， if (條件) { return x; } return y; 應該寫成這樣 return (條件 ? x : y);

10.5.3 在條件運算子中 "?" 之前的表示式

1 2 3 4

如果在 ?: 運算子的 ? 之前出現的表示式中包含了二元運算子，那它應該被 小括號刮起來。例如： (x >= 0) ? x : -x;

10.5.4 特別註解

1 2	在註解中使用 XXX 來標出一些假的但是仍有用的東西。使用 FIXME 來標示 出一些有問題而且壞掉的東西。