JAVA編碼規(guī)范-V1.0.doc

軟通動力公司JAVA編程規(guī)范編號：ISS-STD-JAVA版本:1.0變更記錄日期版本變更說明作者2012626在軟通編碼規(guī)范基礎(chǔ)上修改李博宇、包維、李強、張本晨、沙麗沄20120712在軟通編碼規(guī)范基礎(chǔ)上修改李博宇、包維、李強、張本晨、沙麗沄20120713在軟通編碼規(guī)范基礎(chǔ)上修改李博宇、包維、李強、張本晨、沙麗沄目錄1導(dǎo)言51.1目的51.2范圍51.3角色和職責(zé)51.4術(shù)語定義52格 式62.1.縮進62.2間隔72.3空行82.4類成員的擺放順序82.5文件格式(File Format)82.6行最大長度92.7括號93命名規(guī)則103.1類和接口103.2包103.3get和set方法（屬性的定義）103.4變量113.4.1普通變量：113.4.2常用對象變量113.4.3Static Final變量的命名113.4.4臨時變量114注 釋124.1要求124.2JavaDoc說明124.3類134.4方法144.5代碼的自我說明155編 碼165.1不要使用的結(jié)構(gòu)165.1.1“dowhile”165.1.2return (建議，盡量避免，也可以使用)165.1.3continue165.1.4break165.2不要混合使用遞增運算符和遞減運算符165.3變量初始化175.4魔鬼數(shù)字/字符175.5范圍（scope）171 導(dǎo)言Java語言給了程序員充分的空間隨意編寫自己的代碼，但也正是因為如此，一個程序員自己編寫的代碼往往不能被別的程序員很好的閱讀和理解。1.1 目的本文檔旨在提供一個編碼的標(biāo)準(zhǔn)，以便所有Java代碼在產(chǎn)生的一開始就能夠在整個開發(fā)團隊中保持一致，從而能夠更好的閱讀和修改代碼。1.2 范圍本文檔適用于軟通動力公司項目開發(fā)團隊的所有成員，為了使項目的后期維護和修改變的容易，在每個項目開發(fā)中一定要遵守本文檔中的規(guī)定術(shù)語定義1.3 角色和職責(zé)l 編碼負責(zé)人：本規(guī)范在具體項目中執(zhí)行監(jiān)督負責(zé)人。通過實施Source Review 制度，編程人員在完成自己的一個模塊并提交測試前，由編碼負責(zé)人進行Source Review，不符合本編程規(guī)約的程序一律打回，重新修改，即編碼人你認為自己的程序沒有任何的功能問題。l 編碼人員本規(guī)范的遵守者。1.4 術(shù)語定義l Logger - 系統(tǒng)進行日志輸出了類，為引用第三方（Apache Group）的輸出類，具體用法見 Log輸出規(guī)范的說明。2 格 式2.1 .縮進所有的縮進皆為4個空格。對應(yīng)的括號通常在同一列的位置上。例如： void foo() while ( bar 0 ) Logger.debug(); bar- ; if ( oatmeal = tasty ) Logger.debug(Oatmeal is good and good for you); else if ( oatmeal = yak ) Logger.debug(Oatmeal tastes like sawdust); else Logger.debug(tell me pleeze what iz dis oatmeal); switch( suckFactor ) case 1: Logger.debug(This sucks); break; case 2: Logger.debug(This really sucks); break; default: Logger.debug(whatever); break; 1）所有的縮進是由Space(空格)鍵形成的，而不是Tab鍵。2）所有的if、while和for語句中的狀態(tài)內(nèi)容必須用括號括起來，就算只有一個狀態(tài)。if ( superHero = theTick ) Logger.debug(Spoon!);2.2間隔1）所有的標(biāo)識符都必須被空白字符包圍。 int theTick = 5 ; if ( theTick = 5 ) 這么做唯一可能成為麻煩的是復(fù)雜的布爾分析影響了清晰度，例： if ( ( hero = theTick ) & ( ( sidekick = arthur ) | ( sidekick = speak ) ) )不如這樣： boolean isTickSidekick = ( ( sidekick = arthur ) | ( sidekick = speak ) );if ( ( hero = theTick ) & isTickSidekick ) 2）然而也有一些例外的情況，見下表：例 外 情 況原 由正 確 示 例錯 誤 示 例方 法 名習(xí)慣寫法是在所有方法名之后直接跟上一個左括號foo( i ) ;start() ;args 0 ;tens i ;數(shù) 組習(xí)慣寫法是在所有數(shù)組名之后直接跟上一個左方括號args0 ;tens I ;args 0 ;tens i ;自加、自減運算符習(xí)慣寫法是在所有一元運算符前面或后面直接加上操作數(shù)+count ; i- ;+count ; i - ;造型運算符習(xí)慣寫法是所有造型都不加空格(MyClass)v.get( 3 ) ;(MyClass) v.get( 3 ) ;( MyClass )v.get( 3 ) ;2.3空行應(yīng)該時不時的在各方法之間加入一些空格行來分割大段的代碼；還應(yīng)該在方法與方法之間加入一兩行的空格行。2.4類成員的擺放順序 class Order 1. final attributes2. attributes3. constructors4. methods 必須保持private方法被放置在使用該方法的其他方法之上，而在構(gòu)造器（constructor）之下，即使該構(gòu)造器有可能調(diào)用這些private方法。2.5文件格式(File Format)package必須總保持第一個出現(xiàn)；import其次；再次，任何非javadoc的注釋；然后是javadoc類文件最后便是類。注意：一個文件(File)只能有一個類，內(nèi)部類除外。示例： package misc ; import java.io.* ; import .* ; /* this class does cool stuff * author Joe Programmer */ class SpaceMonkey . 2.6行最大長度不要讓一行代碼的長度超過120個字符，最好是低于80個字符。如果代碼開始向右延伸得很長，你就應(yīng)該考慮把它分割成更多的方法。2.7括號使用括號的目的必須是在表達上不但能夠標(biāo)明優(yōu)先順序，而且有助于使表達更簡單明了。另外，如果某一段代碼有可能產(chǎn)生歧義，也需加括號。3 命名規(guī)則所有的標(biāo)識符只能用字母（A-Z或a-z）和數(shù)字（0-9）。不能有貨幣符號或者其它非ASCII字符，盡量少用數(shù)字。3.1 類和接口所有類和接口標(biāo)識符將都使用混合格表示。每個名稱中的每個單詞首字母必須大寫，同時這個名稱的首字母也必須大寫；其它的字母均小寫，除了縮寫詞之外（它們必須全部大寫）。示例： CustomerSalesOrderTargetURLURLTarget3.2 包所有包名只能用小寫字母。盡量別使包名長度超過8個字符，應(yīng)該避免使用多個詞作為包名。示例：commoncorelang3.3 get和set方法（屬性的定義）使用Eclipse的自動代碼生成get和set方法。變量不要使用前綴，變量的類型在名稱后面表示，如：SystemDate，后面表示類型。以免生成的方法不方便使用。3.4 變量3.4.1 普通變量：變量的命名應(yīng)盡可能采用見名知義，基本命名規(guī)則如下：變量名 = 變量含義 （+ 變量后綴）后綴不一定要使用變量后綴遵循規(guī)則，定義如下：3.4.2 常用對象變量類型前綴VectorvHashMaphmHashtablehtDateDateTimestampTimeCollectioncollIteratoritListLObjectaryObj3.4.3 Static Final變量的命名 Static Final 變量的名字應(yīng)該都大寫，每個單詞之間用 ”_” 連接，并且指出完整含義。3.4.4 臨時變量一般臨時變量沒有具體的意思，所以臨時變量名為：臨時變量名 = 變量前綴 + （Temp或Tmp）；其中有一些C語言延續(xù)下來的常見臨時變量也可以接受：如i , j , k 一般用于表示一個臨時整型變量。4 注 釋大部分注釋盡量用/；對于所有的javadoc的注釋則用/* */；而臨時對代碼塊進行的注釋盡量用/* */。使用時在Eclipse中輸入/*，回車即可自動生成JavaDoc的注釋格式。4.1 要求1、 程序中注釋行應(yīng)不少程序代碼行的40%；2、 類、方法、變量必須注釋說明；3、 注釋內(nèi)容應(yīng)根據(jù)客戶要求的語言進行，原則上，除常量、變量、變量類型等以外的說明盡可能采用中文注釋；4.2 JavaDoc說明1）JavaDoc注釋將用于說明那些被其它類調(diào)用的類、屬性和方法。這些注釋必須出現(xiàn)在所要說明的各項之前。2）JavaDoc注釋一般不會用于說明一些顯而易見的方法，例如：public static void main( String args ) 或public int getX( ) ；3）JavaDoc注釋也不用于說明一些顯而易見的參數(shù)，如：public void setX( int newX ) ；4）諸如servlet和EJB等那些沒有被其它類調(diào)用的類，也不必加JavaDoc注釋。把源碼上交給整個團隊之前，必須先經(jīng)過JavaDoc處理，并全面檢查處理結(jié)果，以確定說明文字確實可讀而且清楚明白。如果JavaDoc注釋能夠在一行內(nèi)寫下，則格式應(yīng)該象下面這樣： /* Used to mark spots */ int x ;如果JavaDoc注釋內(nèi)容在一行內(nèi)容納不下，則其格式應(yīng)該象下面這樣： /* Set how much to grow when growth is needed. * Smaller values will usually save memory, but frequent * reallocation may take a lot of time. * param HowMuch The number of extra ints to allocate when * memory reallocation is required. Values must be greater than * zero. */ public void setExtra( int HowMuch )注意：HTML標(biāo)簽和的作用。迫使一段代碼進行分行，而則讓塊文字以特定的字體表現(xiàn)出來并且保留所有的空格字符。JavaDoc還允許使用其它的HTML標(biāo)簽，但是禁止使用header標(biāo)簽（如, 等）你可以用.加黑文字，也可以用.使文字變?yōu)樾斌w。注意：JavaDoc把每個JavaDoc注釋的第一行劃分出來以用于放置內(nèi)容表。如何標(biāo)識出這部分內(nèi)容的結(jié)束邊界線呢？JavaDoc定義這個標(biāo)志為一個句號后跟一個空格。其它如一個問號后跟一個空格或一個句號后跟一個標(biāo)簽都不是結(jié)束標(biāo)志。如果在句號和之間加一個空格，那么就有結(jié)束標(biāo)志產(chǎn)生了。4.3 類類的JavaDoc說明文件必須包括以下內(nèi)容：（1）簡要的提綱（2）詳細的描述（3）使用該類的示例代碼段（4）用author標(biāo)簽列出作者注意：由于JavaDoc中一個功能（feature）限制，所有示例代碼的每行前面必須加入一個星號，以便保存每行的縮進。例如： /* A vector class optimized for working with ints. * Like the Vector object, except rather than tracking a dynamic * array of pointers to different objects, this is simply a * dynamic array of ints. The advantage is speed and memory * savings. * Example: * * / report longest lines * TextFileIn f = new TextFileIn(blather.txt); * IntVector v = new IntVector(); * int longestLine = 0 ; * boolean done = false ; * while ( ! done ) * * String s = f.readLine(); * if ( s = null ) * * done = true ; * * else * * int sLength = s.length() ; * if ( sLength longestLine ) * * longestLine = sLength ; * * v.append( sLength ); * * * f.close(); * Logger.debug(The longest lines are on line numbers:); * for ( int i = 0 ; i v.length() ; i+ ) * * if ( v.get( i ) = longestLine ) * * Logger.debug( i ); * * * * author Adam Baum * author Justin Case */ public class IntVector4.4 方法方法的JavaDoc說明文檔必須包含以下內(nèi)容：（1）簡要的提綱；（2）詳細的描述（如果有必要在簡要提綱內(nèi)補充說明某些內(nèi)容的話）；（3）用JavaDoc的param標(biāo)簽列出所有參數(shù)（如果有參數(shù)的話）；（4）用JavaDoc的return標(biāo)簽返回出方法的值列表（如果需要返回值的話）；（5）用JavaDoc的exception標(biāo)簽列出所有異常（exception）(如果有異常拋出的話)示例： /* Get a copy of one int. * Retrieve an int relative to the index provided. * param Index Which int (0 is the first int). * return The retrieved int or zero if Index is outside of 0.length. */ public int get( int Index )4.5 代碼的自我說明傻子寫計算機識別的程序；程序員寫人識別的程序。 -Martin Fowler, Refactoring：提高代碼的設(shè)計水平除了要盡力用文件說明程序的復(fù)雜算法，我們還必須盡量通過多用一些標(biāo)識符來使程序的算法易讀。這樣有助于減少將來需要修改程序而不需修改說明文檔而帶來的麻煩。 /* determine if the given year is a leap year. * The Gregorian calendar principal states that a leap year occurs * every fourth year, except every 100 years, except every 400 * years. * param year The year to be tested. Make sure this is a four digit year! * return true if year is a leap year. */ boolean isLeapYear( int year ) boolean y4 = ( ( year % 4 ) = 0 ) ; boolean y100 = ( ( year % 100 ) = 0 ) ; boolean y400 = ( ( year % 400 ) = 0 ) ; return ( y400 | ( y4 & ! y100 ) ); 5 編 碼5.1 不要使用的結(jié)構(gòu)5.1.1 “dowhile” 不要用dowhile循環(huán),用while()循環(huán)5.1.2 return (建議，盡量避免，也可以使用)不要在一個方法的中間使用return，return只能出現(xiàn)在一個方法的末尾。原因：在方法的中間使用return會給今后將方法拆分成幾個更小的方法帶來困難；而且它會迫使開發(fā)者不得不為該方法考慮多于一個的出口點。5.1.3 continue決不要用continu