第01講程序設計基礎Java編碼規(guī)范

1、1 介紹(Introduction)1.1 為什么要有編碼規(guī)范(Why Have Code Conventions)編碼規(guī)范對于程序員而言尤為重要，有以下幾個原因：- 一個軟件的生命周期中，80%的花費在于維護- 幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護- 編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼- 如果你將源碼作為產品發(fā)布，就需要確任它是否被很好的打包并且清晰無誤，一如你已構建的其它任何產品 為了執(zhí)行規(guī)范，每個軟件開發(fā)人員必須一致遵守編碼規(guī)范。每個人。1.2 版權聲明(Acknowledgments)本文檔反映的是Sun MicroSyst

2、ems公司，Java語言規(guī)范中的編碼標準部分。主要貢獻者包括：Peter King，Patrick Naughton，Mike DeMoney，Jonni Kanerva，Kathy Walrath以及Scott Hommel。本文檔現(xiàn)由Scott Hommel維護，有關評論意見請發(fā)至shommel2 文件名(File Names)這部分列出了常用的文件名及其后綴。2.1 文件后綴(File Suffixes)Java程序使用下列文件后綴：文件類別文件后綴Java源文件.javaJava字節(jié)碼文件.class2.2 常用文件名(Common File Names)常用的文件名包括：文件名用途G

3、NUmakefilemakefiles的首選文件名。我們采用gnumake來創(chuàng)建（build）軟件。README概述特定目錄下所含內容的文件的首選文件名3 文件內容編排(File Organization)一個文件由被空行分割而成的段落以及標識每個段落的可選注釋共同組成。超過2000行的程序難以閱讀，應該盡量避免。"Java源文件范例"提供了一個布局合理的Java程序范例。3.1 Java源文件(Java Source Files)每個Java源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關聯(lián)，可以將它們和公共類放入同一個源文件。公共類必須是這個文件中的第

4、一個類或接口。Java源文件還遵循以下規(guī)則：- 開頭注釋（參見"開頭注釋"）- 包和引入語句（參見"包和引入語句"）- 類和接口聲明（參見"類和接口聲明"） 3.1.1 開頭注釋(Beginning Comments)所有的源文件都應該在開頭有一個C語言風格的注釋，其中列出類名、版本信息、日期和版權聲明： /* * Classname * * Version information * * Date * * Copyright notice */ 3.1.2 包和引入語句(Package and Import Statements)在

5、多數(shù)Java源文件中，第一個非注釋行是包語句。在它之后可以跟引入語句。例如： package java.awt; import java.awt.peer.CanvasPeer; 3.1.3 類和接口聲明(Class and Interface Declarations)下表描述了類和接口聲明的各個部分以及它們出現(xiàn)的先后次序。參見"Java源文件范例"中一個包含注釋的例子。 類/接口聲明的各部分注解1類/接口文檔注釋(/*/)該注釋中所需包含的信息，參見"文檔注釋"2類或接口的聲明 3類/接口實現(xiàn)的注釋(/*/)如果有必要的話該注釋應

6、包含任何有關整個類或接口的信息，而這些信息又不適合作為類/接口文檔注釋。4類的(靜態(tài))變量首先是類的公共變量，隨后是保護變量，再后是包一級別的變量(沒有訪問修飾符，access modifier)，最后是私有變量。5實例變量首先是公共級別的，隨后是保護級別的，再后是包一級別的(沒有訪問修飾符)，最后是私有級別的。6構造器 7方法這些方法應該按功能，而非作用域或訪問權限，分組。例如，一個私有的類方法可以置于兩個公有的實例方法之間。其目的是為了更便于閱讀和理解代碼。4 縮進排版(Indentation)4.1 行長度(Line Length)盡量避免一行的長度超過80個字符，因為很多終端

7、和工具不能很好處理之。注意：用于文檔中的例子應該使用更短的行長，長度一般不超過70個字符。4.2 換行(Wrapping Lines)當一個表達式無法容納在一行內時，可以依據(jù)如下一般規(guī)則斷開之：- 在一個逗號后面斷開- 在一個操作符前面斷開- 寧可選擇較高級別(higher-level)的斷開，而非較低級別(lower-level)的斷開- 新的一行應該與上一行同一級別表達式的開頭處對齊- 如果以上規(guī)則導致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進8個空格。 以下是斷開方法調用的一些例子： someMethod(longExpression1, longExpression2, l

8、ongExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 以下是兩個斷開算術表達式的例子。前者更好，因為斷開處位于括號表達式的外邊，這是個較高級別的斷開。 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /PREFFER longName1 = longName2 * (longNam

9、e3 + longName4 - longName5) + 4 * longname6; /AVOID 以下是兩個縮進方法聲明的例子。前者是常規(guī)情形。后者若使用常規(guī)的縮進方式將會使第二行和第三行移得很靠右，所以代之以縮進8個空格 /CONVENTIONAL INDENTATION someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . /INDENT 8 SPACES TO AVOID VERY DEEP INDENTS private static synchronize

10、d horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) . if語句的換行通常使用8個空格的規(guī)則，因為常規(guī)縮進(4個空格)會使語句體看起來比較費勁。比如： /DONT USE THIS INDENTATION if (condition1 && condition2) | (condition3 && condition4) |!(condition5 && condition6) /不好的換行 doSo

11、methingAboutIt(); /易使這行被忽視 /USE THIS INDENTATION INSTEAD if (condition1 && condition2) | (condition3 && condition4) |!(condition5 && condition6) doSomethingAboutIt(); /OR USE THIS if (condition1 && condition2) | (condition3 && condition4) |!(condition5 &&a

12、mp; condition6) doSomethingAboutIt(); 這里有三種可行的方法用于處理三元運算表達式： alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : gamma;5 注釋(Comments)Java程序有兩類注釋：實現(xiàn)注釋(implementation comments)和文檔注釋(document comments)。實現(xiàn)注釋是那些在C+中見過

13、的，使用/*.*/和/界定的注釋。文檔注釋(被稱為"doc comments")是Java獨有的，并由/*.*/界定。文檔注釋可以通過javadoc工具轉換成HTML文件。實現(xiàn)注釋用以注釋代碼或者實現(xiàn)細節(jié)。文檔注釋從實現(xiàn)自由(implementation-free)的角度描述代碼的規(guī)范。它可以被那些手頭沒有源碼的開發(fā)人員讀懂。注釋應被用來給出代碼的總括，并提供代碼自身沒有提供的附加信息。注釋應該僅包含與閱讀和理解程序有關的信息。例如，相應的包如何被建立或位于哪個目錄下之類的信息不應包括在注釋中。在注釋里，對設計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應避免提供

14、代碼中己清晰表達出來的重復信息。多余的的注釋很容易過時。通常應避免那些代碼更新就可能過時的注釋。注意：頻繁的注釋有時反映出代碼的低質量。當你覺得被迫要加注釋的時候，考慮一下重寫代碼使其更清晰。注釋不應寫在用星號或其他字符畫出來的大框里。注釋不應包括諸如制表符和回退符之類的特殊字符。5.1 實現(xiàn)注釋的格式(Implementation Comment Formats)程序可以有4種實現(xiàn)注釋的風格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。5.1.1 塊注釋(Block Comments)塊注釋通常用于提供對文件，方法，數(shù)據(jù)結構和算

15、法的描述。塊注釋被置于每個文件的開始處以及每個方法之前。它們也可以被用于其他地方，比如方法內部。在功能和方法內部的塊注釋應該和它們所描述的代碼具有一樣的縮進格式。塊注釋之首應該有一個空行，用于把塊注釋和代碼分割開來，比如： /* * 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

16、* two * three */ 注意：如果你不使用indent(1)，就不必在代碼中使用/*-，或為他人可能對你的代碼運行indent(1)作讓步。參見"文檔注釋"5.1.2 單行注釋(Single-Line Comments)短注釋可以顯示在一行內，并與其后的代碼具有一樣的縮進層級。如果一個注釋不能在一行內寫完，就該采用塊注釋(參見"塊注釋")。單行注釋之前應該有一個空行。以下是一個Java代碼中單行注釋的例子： if (condition) /* Handle the condition. */ . 5.1.3 尾端注釋(Trailing Comm

17、ents)極短的注釋可以與它們所要描述的代碼位于同一行，但是應該有足夠的空白來分開代碼和注釋。若有多個短注釋出現(xiàn)于大段代碼中，它們應該具有相同的縮進。以下是一個Java代碼中尾端注釋的例子： if (a = 2) return TRUE; /* special case */ else return isPrime(a); /* works only for odd a */ 5.1.4 行末注釋(End-Of-Line Comments)注釋界定符"/"，可以注釋掉整行或者一行中的一部分。它一般不用于連續(xù)多行的注釋文本；然而，它可以用來注釋掉連續(xù)多行的代碼段。以下是所有三

18、種風格的例子： 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 Comments for Javadoc"，其中包含了有關文檔注釋標記的

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

20、數(shù)在內，其文檔注釋的第一行縮進4格，隨后每行都縮進5格。若你想給出有關類、接口、變量或方法的信息，而這些信息又不適合寫在文檔中，則可使用實現(xiàn)塊注釋(見5.1.1)或緊跟在聲明后面的單行注釋(見5.1.2)。例如，有關一個類實現(xiàn)的細節(jié)，應放入緊跟在類聲明后面的實現(xiàn)塊注釋中，而不是放在文檔注釋中。文檔注釋不能放在一個方法或構造器的定義塊中，因為Java會將位于文檔注釋之后的第一個聲明與其相關聯(lián)。6 聲明(Declarations)6.1 每行聲明變量的數(shù)量(Number Per Line)推薦一行一個聲明，因為這樣以利于寫注釋。亦即， int level; / indentation level

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

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

23、t i = 0; i < maxLoops; i+) . 避免聲明的局部變量覆蓋上一級聲明的變量。例如，不要在內部代碼塊中聲明相同的變量名： int count; . myMethod() if (condition) int count = 0; / AVOID! . . 6.4 類和接口的聲明(Class and Interface Declarations)當編寫類和接口時，應該遵守以下格式規(guī)則：- 在方法名與其參數(shù)列表之前的左括號"("間不要有空格- 左大括號""位于聲明語句同行的末尾- 右大括號""另起一行，與相應的聲

24、明語句對齊，除非是一個空語句，""應緊跟在""之后 class Sample extends Object int ivar1; int ivar2; Sample(int i, int j) ivar1 = i; ivar2 = j; int emptyMethod() . - 方法與方法之間以空行分隔 7 語句(Statements)7.1 簡單語句(Simple Statements)每行至多包含一條語句，例如： argv+; / Correct argc-; / Correct argv+; argc-; / AVOID! 7.2 復合語句(Co

25、mpound Statements)復合語句是包含在大括號中的語句序列，形如" 語句 "。例如下面各段。- 被括其中的語句應該較之復合語句縮進一個層次- 左大括號""應位于復合語句起始行的行尾；右大括號""應另起一行并與復合語句首行對齊。- 大括號可以被用于所有語句，包括單個語句，只要這些語句是諸如if-else或for控制結構的一部分。這樣便于添加語句而無需擔心由于忘了加括號而引入bug。 7.3 返回語句(return Statements)一個帶返回值的return語句不使用小括號"()"，除非它們以某種方式

26、使返回值更為顯見。例如： return; return myDisk.size(); return (size ? size : defaultSize); 7.4 if，if-else，if else-if else語句(if, if-else, if else-if else Statements)if-else語句應該具有如下格式： if (condition) statements; if (condition) statements; else statements; if (condition) statements; else if (condition) statements;

27、 else statements; 注意：if語句總是用""和""括起來，避免使用如下容易引起錯誤的格式： if (condition) /AVOID! THIS OMITS THE BRACES ! statement; 7.5 for語句(for Statements)一個for語句應該具有如下格式： for (initialization; condition; update) statements; 一個空的for語句(所有工作都在初始化，條件判斷，更新子句中完成）應該具有如下格式： for (initialization; condition;

28、 update); 當在for語句的初始化或更新子句中使用逗號時，避免因使用三個以上變量，而導致復雜度提高。若需要，可以在for循環(huán)之前(為初始化子句)或for循環(huán)末尾(為更新子句)使用單獨的語句。7.6 while語句(while Statements)一個while語句應該具有如下格式 while (condition) statements; 一個空的while語句應該具有如下格式： while (condition); 7.7 do-while語句(do-while Statements)一個do-while語句應該具有如下格式： do statements; while (condi

29、tion); 7.8 switch語句(switch Statements)一個switch語句應該具有如下格式： switch (condition) case ABC: statements; /* falls through */ case DEF: statements; break; case XYZ: statements; break; default: statements; break; 每當一個case順著往下執(zhí)行時(因為沒有break語句)，通常應在break語句的位置添加注釋。上面的示例代碼中就包含注釋/* falls through */。每個switch語句應包括一

30、個default選項。default選項里的break是冗余的，但可預防以后增加另一個選項后沒有中斷執(zhí)行導致錯誤的情況出現(xiàn)。7.9 try-catch語句(try-catch Statements)一個try-catch語句應該具有如下格式： try statements; catch (ExceptionClass e) statements; 一個try-catch語句后面也可能跟著一個finally語句，不論try代碼塊是否順利執(zhí)行完，它都會被執(zhí)行。 try statements; catch (ExceptionClass e) statements; finally statemen

31、ts; 8 空白(White Space) 8.1 空行(Blank Lines)空行將邏輯相關的代碼段分隔開，以提高可讀性。下列情況應該總是使用兩個空行：- 一個源文件的兩個片段(section)之間- 類聲明和接口聲明之間 下列情況應該總是使用一個空行：- 兩個方法之間- 方法內的局部變量和方法的第一條語句之間- 塊注釋（參見"5.1.1"）或單行注釋（參見"5.1.2"）之前- 一個方法內的兩個邏輯段之間，用以提高可讀性 8.2 空格(Blank Spaces)下列情況應該使用空格：- 一個緊跟著括號的關鍵字應該被空格分開，例如： while (t

32、rue) . 注意：空格不應該置于方法名與其左括號之間。這將有助于區(qū)分關鍵字和方法調用。- 空白應該位于參數(shù)列表中逗號的后面- 所有的二元運算符，除了"."，應該使用空格將之與操作數(shù)分開。一元操作符和操作數(shù)之間不因該加空格，比如：負號("-")、自增("+")和自減("-")。例如： a += c + d; a = (a + b) / (c * d); while (d+ = s+) n+; printSize("size is " + foo + "n"); - for語句

33、中的表達式應該被空格分開，例如： for (expr1; expr2; expr3) - 強制轉型后應該跟一個空格，例如： myMethod(byte) aNum, (Object) x); myMethod(int) (cp + 5), (int) (i + 3) + 1); 9 命名規(guī)范(Naming Conventions)命名規(guī)范使程序更易讀，從而更易于理解。它們也可以提供一些有關標識符功能的信息，以助于理解代碼，例如，不論它是一個常量，包，還是類。標識符類型命名規(guī)則例子包(Packages)一個唯一包名的前綴總是全部小寫的ASCII字母并且是一個頂級域名，通常是com，edu，gov

34、，mil，net，org，或1981年ISO 3166標準所指定的標識國家的英文雙字符代碼。包名的后續(xù)部分根據(jù)不同機構各自內部的命名規(guī)范而不盡相同。這類命名規(guī)范可能以特定目錄名的組成來區(qū)分部門(department)，項目(project)，機器(machine)，或注冊名(login names)。com.sun.engcom.apple.quicktime.v2edu.cmu.cs.bovik.cheese類(Classes)命名規(guī)則：類名是個一名詞，采用大小寫混合的方式，每個單詞的首字母大寫。盡量使你的類名簡潔而富于描述。使用完整單詞，避免縮寫詞(除非該縮寫詞被更廣泛使用，像URL，HT

35、ML)class Raster;class ImageSprite;接口(Interfaces)命名規(guī)則：大小寫規(guī)則與類名相似interface RasterDelegate;interface Storing;方法(Methods)方法名是一個動詞，采用大小寫混合的方式，第一個單詞的首字母小寫，其后單詞的首字母大寫。run();runFast();getBackground();變量(Variables)除了變量名外，所有實例，包括類，類常量，均采用大小寫混合的方式，第一個單詞的首字母小寫，其后單詞的首字母大寫。變量名不應以下劃線或美元符號開頭，盡管這在語法上是允許的。變量名應簡短且富于描述

36、。變量名的選用應該易于記憶，即，能夠指出其用途。盡量避免單個字符的變量名，除非是一次性的臨時變量。臨時變量通常被取名為i，j，k，m和n，它們一般用于整型；c，d，e，它們一般用于字符型。char c;int i;float myWidth;實例變量(Instance Variables)大小寫規(guī)則和變量名相似，除了前面需要一個下劃線int _employeeId;String _name;Customer _customer;常量(Constants)類常量和ANSI常量的聲明，應該全部大寫，單詞間用下劃線隔開。(盡量避免ANSI常量，容易引起錯誤)static final int MIN_

37、WIDTH = 4;static final int MAX_WIDTH = 999;static final int GET_THE_CPU = 1;(hedong注：灰色部分在新的規(guī)范中沒有) 10 編程慣例(Programming Practices)10.1 提供對實例以及類變量的訪問控制(Providing Access to Instance and Class Variables)若沒有足夠理由，不要把實例或類變量聲明為公有。通常，實例變量無需顯式的設置(set)和獲取(gotten)，通常這作為方法調用的副作用的結果 (side effect:The change in the

38、 value of a variable within a routine resulting from assignments outside the routine.美國傳統(tǒng)雙解詞典)。一個具有公有實例變量的恰當例子，是類僅作為數(shù)據(jù)結構，沒有行為。亦即，若你要使用一個結構(struct)而非一個類(如果java支持結構的話)，那么把類的實例變量聲明為公有是合適的。10.2 引用類變量和類方法(Referring to Class Variables and Methods)避免用一個對象訪問一個類的靜態(tài)變量和方法。應該用類名替代。例如： classMethod(); /OK AClass.

39、classMethod(); /OK anObject.classMethod(); /AVOID! 10.3 常量(Constants)位于for循環(huán)中作為計數(shù)器值的數(shù)字常量，除了-1,0和1之外，不應被直接寫入代碼。10.4 變量賦值(Variable Assignments)避免在一個語句中給多個變量賦相同的值。它很難讀懂。例如： fooBar.fChar = barFoo.lchar = 'c' / AVOID! 不要將賦值運算符用在容易與相等關系運算符混淆的地方。例如： if (c+ = d+) / AVOID! (Java disallows) . 應該寫成 if

40、(c+ = d+) != 0) . 不要使用內嵌(embedded)賦值運算符試圖提高運行時的效率，這是編譯器的工作。例如： d = (a = b + c) + r; / AVOID! 應該寫成 a = b + c; d = a + r; 10.5 其它慣例(Miscellaneous Practices)10.5.1 圓括號(Parentheses)一般而言，在含有多種運算符的表達式中使用圓括號來避免運算符優(yōu)先級問題，是個好方法。即使運算符的優(yōu)先級對你而言可能很清楚，但對其他人未必如此。你不能假設別的程序員和你一樣清楚運算符的優(yōu)先級。 if (a = b && c = d)

41、/ AVOID! if (a = b) && (c = d) / RIGHT 10.5.2 返回值(Returning Values)設法讓你的程序結構符合目的。例如： if (booleanExpression) return true; else return false; 應該代之以如下方法： return booleanExpression; 類似地： if (condition) return x; return y; 應該寫做： return (condition ? x : y); 10.5.3 條件運算符"?"前的表達式(Expression

42、s before '?' in the Conditional Operator)如果一個包含二元運算符的表達式出現(xiàn)在三元運算符" ? : "的"?"之前，那么應該給表達式添上一對圓括號。例如： (x >= 0) ? x : -x; 10.5.4 特殊注釋(Special Comments)在注釋中使用XXX來標識某些未實現(xiàn)(bogus)的但可以工作(works)的內容。用FIXME來標識某些假的和錯誤的內容。11 代碼范例(Code Examples)11.1 Java源文件范例(Java Source File Example)下面的例子，展示了如何合理布局一個包含單一公共類的Java源程序。接口的布局與其相似。更多信息參見"類和接口聲明"以及"文擋注釋"。/* * (#)Blah.java 1.82 99/03/18 *