Java編碼規範,在您進行編碼以前應該閱讀的規範

本文轉載於：http://www.web3d.com.cn/new/teach/java3d/2006/11/13/363276161.html

 

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源文件範例」中一個包含註釋的例子。 類/接口聲明的各部分 註解 一、 類/接口文檔註釋(/**……*/) 該註釋中所需包含的信息，參見"文檔註釋" 二、 類或接口的聲明 三、 類/接口實現的註釋(/*……*/)若是有必要的話 該註釋應包含任何有關整個類或接口的信息，而這些信息又不適合做爲類/接口文檔註釋。 四、 類的(靜態)變量 首先是類的公共變量，隨後是保護變量，再後是包一級別的變量(沒有訪問修飾符，access modifier)，最後是私有變量。 五、 實例變量 首先是公共級別的，隨後是保護級別的，再後是包一級別的(沒有訪問修飾符)，最後是私有級別的。 六、 構造器 七、 方法 這些方法應該按功能，而非做用域或訪問權限，分組。例如，一個私有的類方法能夠置於兩個公有的實例方法之間。其目的是爲了更便於閱讀和理解代碼。 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)做讓步。