所有的程序開發手冊都包含了各種規則。一些習慣自由程序人員可能對這些規則很不適應,但是在多個開發人員共同寫作的情況下,這些規則是必需的。這不僅僅是爲了開發效率來考慮,而且也是爲了後期維護考慮。
一、命名規範
定義這個規範的目的是讓項目中所有的文檔都看起來像一個人寫的,增加可讀性,減少項目組中因爲換人而帶來的損失。(這些規範並不是一定要絕對遵守,但是一定要讓程序有良好的可讀性)
> Package 的命名
Package 的名字應該都是由一個小寫單詞組成。
> Class 的命名
Class 的名字必須由大寫字母開頭而其他字母都小寫的單詞組成。
> Class 變量的命名
變量的名字必須用一個小寫字母開頭。後面的單詞用大寫字母開頭。
> Static Final 變量的命名
Static Final 變量的名字應該都大寫,並且指出完整含義。
> 參數的命名
參數的名字必須和變量的命名規範一致。
> 數組的命名
數組應該總是用下面的方式來命名:
- byte[] buffer;
而不是:
- byte buffer[];
> 方法的參數
使用有意義的參數命名,如果可能的話,使用和要賦值的字段一樣的名字:
- SetCounter(int size){
- this.size = size;
- }
二、Java文件樣式
所有的 Java(*.java) 文件都必須遵守如下的樣式規則:
> 版權信息
版權信息必須在java文件的開頭,比如:
- /**
- * Copyright ?2000 Shanghai XXX Co. Ltd.
- * All right reserved.
- */
其他不需要出現在javadoc的信息也可以包含在這裏。
> Package/Imports
package 行要在import行之前,import中標準的包名要在本地的包名之前,而且按照字母順序排列。如果import行中包含了同一個包中的不同子目錄,則應該用*來處理。
- package hotlava.net.stats;
- import java.io.*;
- import java.util.Observable;
- import hotlava.util.Application;
這裏 java.io.* 使用來代替InputStream and OutputStream的。
> Class
接下來的是類的註釋,一般是用來解釋類的。
- /**
- * A class representing a set of packet and byte counters
- * It is observable to allow it to be watched, but only
- * reports changes when the current set is complete
- */
接下來是類定義,包含了在不同的行的 extends 和 implements :
- public class CounterSet
- extends Observable
- implements Cloneable
> Class Fields
接下來是類的成員變量:
- /**
- * Packet counters
- */
- protected int[] packets;
public 的成員變量必須生成文檔(JavaDoc)。proceted、private和 package 定義的成員變量如果名字含義明確的話,可以沒有註釋。
> 存取方法
接下來是類變量的存取的方法。它只是簡單的用來將類的變量賦值獲取值的話,可以簡單的寫在一行上。
- /**
- * Get the counters
- * @return an array containing the statistical data. This array has been
- * freshly allocated and can be modified by the caller.
- */
- public int[] getPackets() { return copyArray(packets, offset); }
- public int[] getBytes() { return copyArray(bytes, offset); }
- public int[] getPackets() { return packets; }
- public void setPackets(int[] packets) { this.packets = packets; }
其它的方法不要寫在一行上。
> 構造函數
接下來是構造函數,它應該用遞增的方式寫(比如:參數多的寫在後面)。
訪問類型 (“public”, “private”等) 和任何“static”,“final”或“synchronized”應該在一行中,並且方法和參數另寫一行,這樣可以使方法和參數更易讀。
- public
- CounterSet(int size){
- this.size = size;
- }
> 克隆方法
如果這個類是可以被克隆的,那麼下一步就是clone方法:
- public
- Object clone()
- {
- try {
- CounterSet obj = (CounterSet)super.clone();
- obj.packets = (int[])packets.clone();
- obj.size = size;
- return obj;
- }catch(CloneNotSupportedException e) {
- throw new InternalError("Unexpected CloneNotSUpportedException: " + e.getMessage());
- }
- }
> 類方法
下面開始寫類的方法:
- /**
- * Set the packet counters
- * (such as when restoring from a database)
- */
- protected final void setArray(int[] r1, int[] r2, int[] r3, int[] r4)throws IllegalArgumentException
- {
- //
- // Ensure the arrays are of equal size
- //
- if (r1.length != r2.length || r1.length != r3.length || r1.length != r4.length)
- throw new IllegalArgumentException("Arrays must be of the same size");
- System.arraycopy(r1, 0, r3, 0, r1.length);
- System.arraycopy(r2, 0, r4, 0, r1.length);
- }
> toString 方法
無論如何,每一個類都應該定義toString 方法:
- public String toString()
- {
- String retval = "CounterSet: ";
- for (int i = 0; i<data.length();i++){
- retval += data.bytes.toString();
- retval += data.packets.toString();
- }
- return retval;
- }
> main 方法
如果main(String[]) 方法已經定義了,那麼它應該寫在類的底部。
三、代碼編寫格式
> 代碼樣式
代碼應該用 unix 的格式,而不是 windows 的(比如:回車變成回車+換行) 。
> 文檔化
必須用 javadoc 來爲類生成文檔。不僅因爲它是標準,這也是被各種 java 編譯器都認可的方法。使用 @author 標記是不被推薦的,因爲代碼不應該是被個人擁有的。
> 縮進
縮進應該是每行2個空格。不要在源文件中保存Tab字符。在使用不同的源代碼管理工具時Tab字符將因爲用戶設置的不同而擴展爲不同的寬度。
如果你使用 UltrEdit 作爲你的 Java 源代碼編輯器的話,你可以通過如下操作來禁止保存Tab字符,方法是通過 UltrEdit中先設定 Tab 使用的長度室2個空格,然後用 Format|Tabs to Spaces 菜單將 Tab 轉換爲空格。
> 頁寬
頁寬應該設置爲80字符。源代碼一般不會超過這個寬度,並導致無法完整顯示,但這一設置也可以靈活調整。在任何情況下,超長的語句應該在一個逗號或者一個操作符後折行。一條語句折行後,應該比原來的語句再縮進2個字符。
> {} 對
{} 中的語句應該單獨作爲一行。例如,下面的第1行是錯誤的第2行是正確的:
- if (i>0) { i ++ }; // 錯誤, { 和 } 在同一行
- if (i>0) {
- i ++
- }; // 正確, { 單獨作爲一行
} 語句永遠單獨作爲一行。
如果 } 語句應該縮進到與其相對應的 { 那一行相對齊的位置。
> 括號
左括號和後一個字符之間不應該出現空格,同樣,右括號和前一個字符之間也不應該出現空格。下面的例子說明括號和空格的錯誤及正確使用:
- CallProc( AParameter ); // 錯誤
- CallProc(AParameter); // 正確
不要在語句中使用無意義的括號。括號只應該爲達到某種目的而出現在源代碼中。下面的例子說明錯誤和正確的用法:
- if ((I) = 42) { // 錯誤 - 括號毫無意義
- if (I == 42) or (J == 42) then // 正確 - 的確需要括號
四、程序編寫規範
> exit()
exit除了在main中可以被調用外,其他的地方不應該調用。因爲這樣做不給任何代碼代碼機會來截獲退出。一個類似後臺服務地程序不應該因爲某一個庫模塊決定了要退出就退出。
> 異常
申明的錯誤應該拋出一個RuntimeException或者派生的異常。
頂層的main()函數應該截獲所有的異常,並且打印(或者記錄在日誌中)在屏幕上。
> 垃圾收集
JAVA使用成熟的後臺垃圾收集技術來代替引用計數。但是這樣會導致一個問題:你必須在使用完對象的實例以後進行清場工作。比如一個prel的程序員可能這麼寫:
- ...
- {
- FileOutputStream fos = new FileOutputStream(projectFile);
- project.save(fos, "IDE Project File");
- }
- ...
除非輸出流一出作用域就關閉,非引用計數的程序語言,比如JAVA,是不能自動完成變量的清場工作的。必須象下面一樣寫:
- FileOutputStream fos = new FileOutputStream(projectFile);
- project.save(fos, "IDE Project File");
- fos.close();
> Clone
下面是一種有用的方法:
- implements Cloneable
- public
- Object clone()