Java編碼規范 說明 1.1 為什麼要有編碼規范 編碼規范對於程序員而言尤為重要,有以下幾個原因: 一個軟件的生命周期中,80%的花費在於維護。 幾乎沒有任何一個軟件,在其整個生命周期中,均由最初的開發人員來維護。 編碼規范可以改善軟件的可讀性,可以讓程序員盡快而徹底地理解新的代碼。
如果你將源碼作為產品發佈,就需要確任它是否被很好的打包並且清晰無誤,一如你已構建的其它任何產品。 為瞭執行規范,每個軟件開發人員必須一致遵守編碼規范。每個人!!! 1.2版權聲明 本文檔反映的是Sun MicroSystems公司,Java語言規范中的編碼標準部分。主要貢獻者包括:Peter King,Patrick Naughton,Mike DeMoney,Jonni Kanerva,Kathy Walrath以及Scott Hommel。本文檔現由Scott Hommel維護,有關評論意見請發至shommel@eng.sun.com 2. 文件名(File Names) 這部分列出瞭常用的文件名及其後綴。 2.1 文件後綴(File Suffixes) Java程序使用下列文件後綴:
文件類別 文件後綴 Java源文件 .java
Java字節碼文件 .class
2.2 常用文件名(Common File Names)
常用的文件名包括:
文件名 用途
GNUmakefile makefiles的首選文件名。我們采用gnumake來創建(build)軟件。 README 概述特定目錄下所含內容的文件的首選文件名 3. 文件組織(File Organization) 一個文件由被空行分割而成的段落以及標識每個段落的可選註釋共同組成。超過2000行的程序難以閱讀,應該盡量避免。“Java源文件范例”提供瞭一個佈局合理的Java程序范例。 3.1 Java源文件(Java Source Files) 每個Java源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關聯,可以將它們和公共類放入同一個源文件。公共類必須是這個文件中的第一個類或接口。 Java源文件還遵循以下規則: 開頭註釋(參見"開頭註釋")
包和引入語句(參見"包和引入語句")
類和接口聲明(參見"類和接口聲明") 3.1.1 開頭註釋(Beginning Comments) 所有的源文件都應該在開頭有一個C語言風格的註釋,其中列出類名、版本信息、日期和版權聲明: /*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/ 3.1.2 包和引入語句(Package and Import Statements)
在多數Java源文件中,第一個非註釋行是包語句。在它之後可以跟引入語句。 例如:
package java.awt;
import java.awt.peer.CanvasPeer; 3.1.3 類和接口聲明(Class and Interface Declarations) 下表描述瞭類和接口聲明的各個部分以及它們出現的先後次序。參見“Java源文件范例”中一個包含註釋的例子。
類/接口聲明的各部分 註解 1、 類/接口文檔註釋(/**……*/) 該註釋中所需包含的信息,參見"文檔註釋"
2、 類或接口的聲明
3、 類/接口實現的註釋(/*……*/)如果有必要的話 該註釋應包含任何有關整個類或接口的信息,而這些信息又不適合作為類/接口文檔註釋。
4、 類的(靜態)變量 首先是類的公共變量,隨後是保護變量,再後是包一級別的變量(沒有訪問修飾符,access modifier),最後是私有變量。
5、 實例變量 首先是公共級別的,隨後是保護級別的,再後是包一級別的(沒有訪問修飾符),最後是私有級別的。
6、 構造器 7、 方法 這些方法應該按功能,而非作用域或訪問權限,分組。例如,一個私有的類方法可以置於兩個公有的實例方法之間。其目的是為瞭更便於閱讀和理解代碼。
4. 縮進排版(Indentation) 4個空格常被作為縮進排版的一個單位。縮進的確切解釋並未詳細指定(空格 vs. 制表符)。一個制表符等於8個空格(而非4個)。 4.1 行長度(Line Length) 盡量避免一行的長度超過80個字符,因為很多終端和工具不能很好處理之。 註意:用於文檔中的例子應該使用更短的行長,長度一般不超過70個字符。 4.2 換行(Wrapping Lines) 當一個表達式無法容納在一行內時,可以依據如下一般規則斷開之: 在一個逗號後面斷開。 在一個操作符前面斷開。 寧可選擇較高級別(higher-level)的斷開,而非較低級別(lower-level)的斷開。 新的一行應該與上一行同一級別表達式的開頭處對齊。 如果以上規則導致你的代碼混亂或者使你的代碼都堆擠在右邊,那就代之以縮進8個空格。 以下是斷開方法調用的一些例子: someMethod(longExpression1, longExpression2, longExpression3,
longExpression4, longExpression5);
var = someMethod1(longExpression1,
someMethod2(longExpression2,
longExpression3)); 以下是兩個斷開算術表達式的例子。前者更好,因為斷開處位於括號表達式的外邊,這是個較高級別的斷開。 longName1 = longName2 * (longName3 + longName4 – longName5)
+ 4 * longname6; //PREFFER
longName1 = longName2 * (longName3 + longName4
– longName5) + 4 * longname6; //AVOID 以下是兩個縮進方法聲明的例子。前者是常規情形。後者若使用常規的縮進方式將會使第二行和第三行移得很靠右,所以代之以縮進8個空格 //CONVENTIONAL INDENTATION
someMethod(int anArg, Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
…
} //INDENT 8 SPACES TO AVOID VERY DEEP INDENTS
private static synchronized horkingLongMethodName(int anArg,
Object anotherArg, String yetAnotherArg,
Object andStillAnother) {
…
}
if語句的換行通常使用8個空格的規則,因為常規縮進(4個空格)會使語句體看起來比較費勁。比如: //DON’T USE THIS INDENTATION
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) { //BAD WRAPS
doSomethingAboutIt(); //MAKE THIS LINE EASY TO MISS
} //USE THIS INDENTATION INSTEAD
if ((condition1 && condition2)
|| (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
} //OR USE THIS
if ((condition1 && condition2) || (condition3 && condition4)
||!(condition5 && condition6)) {
doSomethingAboutIt();
}
這裡有三種可行的方法用於處理三元運算表達式: alpha = (aLongBooleanExpression) ? beta : gamma;
alpha = (aLongBooleanExpression) ? beta
: gamma;
alpha = (aLongBooleanExpression)
? beta
: gamma; 5. 註釋(Comments) Java程序有兩類註釋:實現註釋(implementation comments)和文檔註釋(document comments)。實現註釋是那些在C++中見過的,使用/*…*/和//界定的註釋。文檔註釋(被稱為“doc comments”)是Java獨有的,並由/**…*/界定。文檔註釋可以通過javadoc工具轉換成HTML文件。 實現註釋用以註釋代碼或者實現細節。文檔註釋從實現自由(implementation-free)的角度描述代碼的規范。它可以被那些手頭沒有源碼的開發人員讀懂。 註釋應被用來給出代碼的總括,並提供代碼自身沒有提供的附加信息。註釋應該僅包含與閱讀和理解程序有關的信息。例如,相應的包如何被建立或位於哪個目錄下之類的信息不應包括在註釋中。 在註釋裡,對設計決策中重要的或者不是顯而易見的地方進行說明是可以的,但應避免提供代碼中己清晰表達出來的重復信息。多餘的的註釋很容易過時。通常應避免那些代碼更新就可能過時的註釋。
註意:頻繁的註釋有時反映出代碼的低質量。當你覺得被迫要加註釋的時候,考慮一下重寫代碼使其更清晰。 註釋不應寫在用星號或其他字符畫出來的大框裡。註釋不應包括諸如制表符和回退符之類的特殊字符。 5.1 實現註釋的格式(Implementation Comment Formats) 程序可以有4種實現註釋的風格:塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。 5.1.1 塊註釋(Block Comments) 塊註釋通常用於提供對文件,方法,數據結構和算法的描述。塊註釋被置於每個文件的開始處以及每個方法之前。它們也可以被用於其他地方,比如方法內部。在功能和方法內部的塊註釋應該和它們所描述的代碼具有一樣的縮進格式。 塊註釋之首應該有一個空行,用於把塊註釋和代碼分割開來,比如: /*
* Here is a block comment.
*/ 塊註釋可以以/*-開頭,這樣indent(1)就可以將之識別為一個代碼塊的開始,而不會重排它。 /*-
* Here is a block comment with some very special
* formatting that I want indent(1) to ignore.
*
* one
* two
* three
*/
註意:如果你不使用indent(1),就不必在代碼中使用/*-,或為他人可能對你的代碼運行indent(1)作讓步。
作者“陳彥志的博客”