JAVA編碼規(guī)范

1、1 介紹(Introduction)1.1 為什么要有編碼規(guī)范(Why Have Code Conventions)編碼規(guī)范對于程序員而言尤為重要，有以下幾個原因：（1）一個軟件的生命周期中，80%的花費在于維護。（2）幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護。（3）編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼。（4）如果你將源碼作為產(chǎn)品發(fā)布，就需要確任它是否被很好的打包并且清晰無誤，一如你已構(gòu)建的其它任何產(chǎn)品。2 文件名(File Names)這部分列出了常用的文件名及其后綴。2.1 文件后綴(File Suffixes)Java程序使用下列文

2、件后綴：文件類別文件后綴Java源文件.javaJava字節(jié)碼文件.class2.2 常用文件名(Common File Names)常用的文件名包括：文件名用途GNUmakefilemakefiles的首選文件名。我們采用gnumake來創(chuàng)建（build）軟件。README概述特定目錄下所含內(nèi)容的文件的首選文件名3 文件組織(File Organization)一個文件由被空行分割而成的段落以及標識每個段落的可選注釋共同組成。超過2000行的程序難以閱讀，應該盡量避免。Java源文件范例提供了一個布局合理的Java程序范例。3.1 Java源文件(Java Source Files)每個Ja

3、va源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關(guān)聯(lián)，可以將它們和公共類放入同一個源文件。公共類必須是這個文件中的第一個類或接口。Java源文件還遵循以下規(guī)則：（1）開頭注釋（2）包和引入語句（3）類和接口聲明 開頭注釋(Beginning Comments)所有的源文件都應該在開頭有一個C語言風格的注釋，其中列出類名、版本信息、日期和版權(quán)聲明：/* * Classname* Version information* Date* Copyright notice*/ 包和引入語句(Package and Import Statements)在多數(shù)Java源文件中，第一個非注

4、釋行是包語句。在它之后可以跟引入語句。例如：package java.awt； 類和接口聲明(Class and Interface Declarations)下表描述了類和接口聲明的各個部分以及它們出現(xiàn)的先后次序。類/接口聲明的各部分注解1類/接口文檔注釋(/*/)該注釋中所需包含的信息2類或接口的聲明3類/接口實現(xiàn)的注釋(/*/)如果有必要的話該注釋應包含任何有關(guān)整個類或接口的信息，而這些信息又不適合作為類/接口文檔注釋。4類的(靜態(tài))變量首先是類的公共變量，隨后是保護變量，再后是包一級別的變量(沒有訪問修飾符，access modifier)，最后是私有變量。5實例變量首先是公共級別的，

5、隨后是保護級別的，再后是包一級別的(沒有訪問修飾符)，最后是私有級別的。6構(gòu)造器7方法這些方法應該按功能，而非作用域或訪問權(quán)限，分組。例如，一個私有的類方法可以置于兩個公有的實例方法之間。其目的是為了更便于閱讀和理解代碼。4 縮進排版(Indentation)4個空格常被作為縮進排版的一個單位?？s進的確切解釋并未詳細指定(空格 vs. 制表符)。一個制表符等于8個空格(而非4個)。4.1 行長度(Line Length)盡量避免一行的長度超過80個字符，因為很多終端和工具不能很好處理之。注意：用于文檔中的例子應該使用更短的行長，長度一般不超過70個字符。4.2 換行(Wrapping Line

6、s)當一個表達式無法容納在一行內(nèi)時，可以依據(jù)如下一般規(guī)則斷開之：（1）在一個逗號后面斷開。（2）在一個操作符前面斷開。（3）寧可選擇較高級別(higher-level)的斷開，而非較低級別(lower-level)的斷開。（4）新的一行應該與上一行同一級別表達式的開頭處對齊。（5）如果以上規(guī)則導致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進8個空格。 以下是斷開方法調(diào)用的一些例子：someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);var = s

7、omeMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 以下是兩個斷開算術(shù)表達式的例子。前者更好，因為斷開處位于括號表達式的外邊，這是個較高級別的斷開。longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /PREFFERlongName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /AVOID以下是兩個縮進方法

8、聲明的例子。前者是常規(guī)情形。后者若使用常規(guī)的縮進方式將會使第二行和第三行移得很靠右，所以代之以縮進8個空格/CONVENTIONAL INDENTATIONsomeMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . /INDENT 8 SPACES TO AVOID VERY DEEP INDENTSprivate static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yet

9、AnotherArg, Object andStillAnother) .if語句的換行通常使用8個空格的規(guī)則，因為常規(guī)縮進(4個空格)會使語句體看起來比較費勁。比如：/DONT USE THIS INDENTATIONif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS/USE THIS INDENTATION INSTEADif (condition1

10、& condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt();/OR USE THISif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt();這里有三種可行的方法用于處理三元運算表達式：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongBoolean

11、Expression) ? beta : gamma;alpha = (aLongBooleanExpression) ? beta : gamma; 5 注釋(Comments)Java程序有兩類注釋：實現(xiàn)注釋(implementation comments)和文檔注釋(document comments)。實現(xiàn)注釋是那些在C+中見過的，使用/*.*/和/界定的注釋。文檔注釋(被稱為doc comments)是Java獨有的，并由/*.*/界定。文檔注釋可以通過javadoc工具轉(zhuǎn)換成HTML文件。實現(xiàn)注釋用以注釋代碼或者實現(xiàn)細節(jié)。文檔注釋從實現(xiàn)自由(implementation-free)

12、的角度描述代碼的規(guī)范。它可以被那些手頭沒有源碼的開發(fā)人員讀懂。注釋應被用來給出代碼的總括，并提供代碼自身沒有提供的附加信息。注釋應該僅包含與閱讀和理解程序有關(guān)的信息。例如，相應的包如何被建立或位于哪個目錄下之類的信息不應包括在注釋中。在注釋里，對設計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應避免提供代碼中己清晰表達出來的重復信息。多余的的注釋很容易過時。通常應避免那些代碼更新就可能過時的注釋。注意：頻繁的注釋有時反映出代碼的低質(zhì)量。當你覺得被迫要加注釋的時候，考慮一下重寫代碼使其更清晰。注釋不應寫在用星號或其他字符畫出來的大框里。注釋不應包括諸如制表符和回退符之類的特殊字符。5.

13、1 實現(xiàn)注釋的格式(Implementation Comment Formats)程序可以有4種實現(xiàn)注釋的風格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。 塊注釋(Block Comments)塊注釋通常用于提供對文件，方法，數(shù)據(jù)結(jié)構(gòu)和算法的描述。塊注釋被置于每個文件的開始處以及每個方法之前。它們也可以被用于其他地方，比如方法內(nèi)部。在功能和方法內(nèi)部的塊注釋應該和它們所描述的代碼具有一樣的縮進格式。塊注釋之首應該有一個空行，用于把塊注釋和代碼分割開來，比如：/* * Here is a block comment.*/塊注釋可以以

14、/*-開頭，這樣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)作讓步。 單行注釋(Single-Line Comments)短注釋可以顯示在一行內(nèi)，并與其后的代碼具有一樣的縮進層級。如果一個注釋不能在一行內(nèi)寫完，就該采用塊注釋

15、。單行注釋之前應該有一個空行。以下是一個Java代碼中單行注釋的例子：if (condition) /* Handle the condition. */ . 尾端注釋(Trailing Comments)極短的注釋可以與它們所要描述的代碼位于同一行，但是應該有足夠的空白來分開代碼和注釋。若有多個短注釋出現(xiàn)于大段代碼中，它們應該具有相同的縮進。以下是一個Java代碼中尾端注釋的例子：if (a = 2) return TRUE; /* special case */ else return isPrime(a); /* works only for odd a */ 行末注釋(End-Of-L

16、ine Comments)注釋界定符/，可以注釋掉整行或者一行中的一部分。它一般不用于連續(xù)多行的注釋文本；然而，它可以用來注釋掉連續(xù)多行的代碼段。以下是所有三種風格的例子：if (foo 1) / Do a double-flip. .else return false; / Explain why here./if (bar 1) / / Do a triple-flip./ ./else / return false;/5.2 文檔注釋(Documentation Comments)注意：此處描述的注釋格式之范例，參見Java源文件范例若想了解更多，參見How to Write Doc C

17、omments for Javadoc，其中包含了有關(guān)文檔注釋標記的信息(return, param, see)：若想了解更多有關(guān)文檔注釋和javadoc的詳細資料，參見javadoc的主頁：文檔注釋描述Java的類、接口、構(gòu)造器，方法，以及字段(field)。每個文檔注釋都會被置于注釋定界符/*.*/之中，一個注釋對應一個類、接口或成員。該注釋應位于聲明之前：/* * The Example class provides .*/public class Example . 注意頂層(top-level)的類和接口是不縮進的，而其成員是縮進的。描述類和接口的文檔注釋的第一行(/*)不需縮進；隨

18、后的文檔注釋每行都縮進1格(使星號縱向?qū)R)。成員，包括構(gòu)造函數(shù)在內(nèi)，其文檔注釋的第一行縮進4格，隨后每行都縮進5格。若你想給出有關(guān)類、接口、變量或方法的信息，而這些信息又不適合寫在文檔中，則可使用實現(xiàn)塊注釋(見)或緊跟在聲明后面的單行注釋(見5.1.2)。例如，有關(guān)一個類實現(xiàn)的細節(jié)，應放入緊跟在類聲明后面的實現(xiàn)塊注釋中，而不是放在文檔注釋中。文檔注釋不能放在一個方法或構(gòu)造器的定義塊中，因為Java會將位于文檔注釋之后的第一個聲明與其相關(guān)聯(lián)。6 聲明(Declarations)6.1 每行聲明變量的數(shù)量(Number Per Line)推薦一行一個聲明，因為這樣以利于寫注釋。亦即，int le

19、vel; / indentation levelint size; / size of table要優(yōu)于，int level, size; 不要將不同類型變量的聲明放在同一行，例如：int foo, fooarray; /WRONG! 注意：上面的例子中，在類型和標識符之間放了一個空格，另一種被允許的替代方式是使用制表符：intlevel; / indentation levelintsize; / size of tableObjectcurrentEntry; / currently selected table entry 6.2 初始化(Initialization)盡量在聲明局部變量

20、的同時初始化。唯一不這么做的理由是變量的初始值依賴于某些先前發(fā)生的計算。6.3 布局(Placement)只在代碼塊的開始處聲明變量。（一個塊是指任何被包含在大括號和中間的代碼。）不要在首次用到該變量時才聲明之。這會把注意力不集中的程序員搞糊涂，同時會妨礙代碼在該作用域內(nèi)的可移植性。void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 該規(guī)則的一個例外是for循環(huán)的索引變量for (int i = 0; i = 0) ? x

21、 : -x; 特殊注釋(Special Comments)在注釋中使用XXX來標識某些未實現(xiàn)(bogus)的但可以工作(works)的內(nèi)容。用FIXME來標識某些假的和錯誤的內(nèi)容。11 代碼范例(Code Examples)11.1 Java源文件范例(Java Source File Example)下面的例子，展示了如何合理布局一個包含單一公共類的Java源程序。接口的布局與其相似。/* * (#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 Sun Microsystems, Inc. * 901 San Antonio Road

22、, Palo Alto, California, 94303, U.S.A. * All rights reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. (Confidential Information). You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. */package java.blah;import java.blah.blahdy.BlahBlah;/* * Class description goes here. * * version 1.82 18 Mar 1999 * author Firstname Lastname */public class Blah extends SomeClass /* A class implementation comment can g