1、知識管理系統代碼編寫規范一、介紹本文檔為知識管理系統代碼編寫規范，為保證代碼風格的一致性和后期的可維護性，文檔講述的內容要求所有開發人員必須遵守。本規范主要參考了GoogleJavaStyle,包括了其他一些業界約定俗成的公約和普遍采用的標準。本規范并非最終標準，一些規定還需再做商討。術語說明本文檔除非特殊說明，否則：類（class）統指普通類、枚舉類、接口和注解類型。注釋（comment）只用來指實現注釋（implementationcomments）。我們不使用文檔注釋”這樣的說法，而會直接說Javadoo其他術語說明”，將在文檔中需要說明的地方單獨說明。文檔說明本文檔中的代碼并不一定符合

2、所有規范。即使這些代碼遵循本規范，但這不是唯一的代碼方式。例子中可選的格式風格也不應該作為強制執行的規范。二、源碼文件基礎文件名源文件以其最頂層的類名來命名，大小寫敏感，文件擴展名為.java。文件編碼：UTF-8源碼文件使用UTF-8編碼。特殊字符空格字符除了換行符外，ASCII水平空白字符（0x20）是源碼文件中唯一支持的空格字符。這意味著：其他空白字符將被轉義。Tab字符不被用作縮進控制。特殊轉義字符串任何需要轉義字符串表示的字符（例如b,t,n,f,r,",'和等），采用這種轉義字符串的方式表示，而不采用對應字符的八進制數（例如012）或Unicode碼（例如u000

3、a）表示。非ASCII字符對于其余非ASCII字符，直接使用Unicode字符（例如°°）,或者對應的Unicode碼（例如u221e）轉義都是允許的。唯一需要考慮的是，何種方式更能使代碼容易閱讀和理解。注意：在使用Unicode碼轉義，或者甚至是有時直接使用Unicode字符的時候，添加一點說明注釋將對別人讀懂代碼很有幫助。三、源碼文件結構源碼文件按照先后順序，由以下幾部分組成：license或者copyright聲明信息。（如果需要聲明）包（package）聲明語句。import語句。類聲明（每個源碼文件只能有一個頂級類）。每個部分之間應該只有一行空行作為間隔。lice

4、nse或者copyright的聲明信息。如果需要聲明license或copyright信息，應該在文件開始時聲明。包聲明包聲明的行沒有行長度的限制。單行長度限制不適用于包聲明。import語句不使用通配符import即，不要出現類似這樣的import語句：import.*;沒有行長度限制import語句的行沒有行長度的限制。單行長度限制不適用于import語句所在行。順序和空行import語句應該被分為幾個組，每個組之間由單行的空行隔開。分組的順序如下：所有的靜態導入為歸為一組。（項目自帶包）包白import歸為一組。第三方包。每個頂級包歸為一組。第三方包之間按ASCII碼排序。例如：andr

5、oid,com,junit,org,sunjava包歸為一組。javax包歸為一組。同一組內的import語句之間不應用空行隔開。同一組中的import語句按ASCII碼排序。類聲明只聲明一個頂級類每個源碼文件中只能有一個頂級類。例外：，該文件中可沒有package-info類。類成員順序類成員的順序對代碼的易讀性有很大影響，但這也不存在唯一的通用法則。不同的類可能有不同的排序方式。重要的是，每個類都要按照一定的邏輯規律排序。維護者應該要能解釋這種排序邏輯。比如,新的方法不能總是習慣性地添加到類的結尾，因為這樣就是按時間順序而非某種邏輯來排序的。重載方法：不應該分開當一個類有多個構造函數，或者

6、多個同名成員方法時，這些函數應該寫在一起，不應該被其他成員分開。四、格式術語說明：塊狀結構(block-likeconstruct)指類、成員函數和構造函數的實現部分(大括號中間部分)。注意，在后面的節中講到數組初始化，所有的數組初始化都可以被認為是一個塊狀結構(非強制)。大括號大括號不可省略大括號一般用在if,else,for,do和while等語句。即使當它的實現為空或者只有一句話時，也需要使用。非空語句塊采用K&R風格對于非空語句塊，大括號遵循Kernighan&Ritchie風格：左大括號前不換行。左大括號后換行。右大括號前換行。如果右大括號結束一個語句塊或者函數體、構

7、造函數體或者有命名的類體，則右大括號后換行，否則不要換行。例如，當右大括號后面接else或者逗號時，不應該換行。例子：returnnewMyClass()Overridepublicvoidmethod()if(condition()trysometing();catch(ProblemExceptione)recover。；;一些例外的情況，將在節講枚舉類型的時候講到。空語句塊：可以用簡潔版本一個空的語句塊，大括號可以簡潔地寫成,不需要換行。如果它是一個多塊語句的一部分(if/else或try/catch/finally),即使大括號內沒內容，右大括號也要換行。例子：voiddoNothin

8、g()語句塊的縮進：4空格每當一個新的語句塊產生，縮進就增加兩個空格。當這個語句塊結束時，縮進恢復到上一層級的縮進格數。縮進要求對整個語句塊中的代碼和注釋都適用。(例子可參考之前節中的例子)。一行最多只有一句代碼每句代碼的結束都需要換行。行長度PM制：80或100不同的項目可以選擇采用80個字符或者100個字符作為限制。除了以下幾個特殊情況外，其他代碼內容都需要遵守這個長度限制。這在節會有詳細解釋。例外：1 .按照行長度限制，無法實現地方（例如：Javadoc中超長的URL地址，或者一個超長的JSNI方法的引用）；2 .package和import語句不受長度限制。（見、節）；3 .注釋中的命

9、令行指令行，將被直接復制到shell中執行的。換行術語說明：當一行代碼按照其他規范都合法，只是為了避免超出行長度限制而換行時，稱為長行斷行。長行斷行，沒有一個適合所有場景的全面、確定的規范。但很多相同的情況，我們經常使用一些行之有效的斷行方法。注意：將長行封裝為函數，或者使用局部變量的方法，也可以解決一些超出行長度限制的情況。并非一定要斷行。在何處斷行斷行的主要原則是：選擇在更高一級的語法邏輯的地方斷行。其他一些原則如下：1 .在一個逗號后面斷開。2 .在一個操作符前面斷開（二號和foreach語句的冒號除外）。3 .在調用函數或者構造函數需要斷行時，與函數名相連的左括號要在一行。也就是在左括

10、號之后斷行。斷行的縮進：至少8個字符當斷行之后，在第一行之后的行，我們叫做延續行。每一個延續行在第一行的基礎上至少縮進四個字符。當原行之后有多個延續行的情況，縮進可以大于8個字符。如果多個延續行之間由同樣的語法元素斷行，它們可以采用相同的縮進。節介紹水平對齊中，解決了使用多個空格與之前行縮進對齊的問題。空白垂直空白以下情況需使用一個空行：類成員之間需要空行隔開：字段、構造函數、方法、內部類、靜態初始化語句塊（staticinitializers）、實例初始化語句塊（instanceinitializers）。例外：連續字段之間的空白行不是必需的。一般多個字段中間的空行，是為了對字段做邏輯上的分

11、組。在函數體內，語句的邏輯分組間使用空行。類的第一個成員之前，或者最后一個成員結束之后，用空行間隔。（可選）本文檔中其他部分介紹的需要空行的情況。（例如節中的import語句）單空行時使用多行空行是允許的，但是不要求也不鼓勵。水平空白除了語法和規范的其他規則，詞語分隔、注釋和Javadoc外，水平的ASCII空格只在以下情況出現：所有保留的關鍵字與緊接它之后的位于同一行的左括號（）之間需要用空格隔開。（例如if、for、catch）所有保留的關鍵字與在它之前的右大括號（）之間需要空格隔開。（例如else、catch）在左大寸號（）之前都需要空格隔開。只有兩種例外：SomeAnnotation（

12、a,b）String口x="foo"所有的二元運算符和三元運算符的兩邊，都需要空格隔開。一元操作符和操作數之間不應該加空格，比如：負號（“-”），自增（“+”）和自減（“-”）。例：i+;逗號、冒號、分號和右括號之后。如果在一條語句后做注釋，則雙斜杠.例外：如果注解只有一個，并且不帶參數。則它可以和類或方法名放在同一行。例如：OverridepublicinthashCode（）注解應用到字段時，也是緊接Javadoc之后。不同的是，多個注解可以放在同一行。例如：PartialMockDataLoaderloader;對于參數或者局部變量使用注解的情況，沒有特定的規范。注釋

13、語句塊的注釋風格注釋的縮進與它所注釋的代碼縮進相同。可以采用/*/進行注釋，也可以用.進行注釋。當使用/*.*/進行多行注釋時，每一行都應該以*開始，并且*應該上下對齊。注意文字和注釋符之間有一個空格（水平空白）。例如：/*Thisis*evendothis.*/*/提示：多行注釋時，如果你希望集成開發環境能自動對齊注釋，你應該使用/*.*/，.一般不會自動對齊。修飾符多個類和字段的修飾符，按JavaLanguageSpecification中介紹的先后順序排序。具體是：publicprotectedprivateabstractstaticfinaltransientvolatilesync

14、hronizednativestrictfp數字型的字面值long類型的字面值使用大寫L為后綴，永遠不要使用小寫l（避免和1混淆）。例如：00L五、命名適用于所有命名標識符的通用規范標示符只應該使用ASCII字母、數字，字母大小寫敏感。因此所有的標示符，都應該能匹配正則表達式w+。標示符不需要使用特殊白前綴或后綴，如name_,mName,s_name和kName,在Java編程風格中都不再使用。不同類型的標示符規范包名包名全部用小寫字母，將各單詞簡單地連在一起（不使用下劃線）。例如：，不要使用或。類名類名都以UpperCamelCase風格編寫。類名一般使用名詞或名詞短語，例如：Charac

15、ter或ImmutableList。接口名稱一般也使用名詞或名詞短語（如：List）,有時也可以使用形容詞或形容詞短語（如：Readable）。還沒有特定的規則或行之有效的約定來命名注解類型。測試類的命名，應該以它所測試的類的名字為開頭，并在最后加上Test結尾。例如：HashTest、HashIntegrationTest。方法名方法名都以lowerCamelCase風格編寫。方法命名一般使用動詞或者動詞短語，例如：sendMessage或stop。在JUnit的測試方法中，可以使用下劃線，用來區分邏輯組件的名字，經常使用如下的結構：test<MethodUnderTest>_&

16、lt;state>。例如：testPop_emptyStack。并不存在唯一正確的方式來命名測試方法。常量名常量命名，全部使用大寫字符，詞與詞之間用下劃線隔開。(CONSTANCE_CASE常量的定義：每個常量都是一個靜態final字段，但不是所有靜態final字段都是常量。在決定一個字段是否是一個常量時，考慮它是否真的感覺像是一個常量。例如，如果任何一個該實例的觀測狀態是可變的，則它幾乎肯定不會是一個常量。只是永遠不打算改變對象一般是不夠的，它要真的一直不變才能將它示為常量。下面是常量和非常量的例子：();StaticMethod();*/publicintmethod(Stringp

17、1)或者為單行格式：/*AnespeciallyshortbitofJavadoc.*/通用格式在任何時候使用都是可以的。當Javadoc塊只有一行時，可以使用單行格式來替代通用格式。段落空白行：是指Javadoc中，上下兩個段落之間只有上下對齊的*字符的行。每個段落的第一行在第一個字符之前，有一個<p>標簽，并且之后不要有任何空格。Javadoc標記所有標準的Javadoc標記，應該按照如下的順序添加：param、return、throws、deprecated。并且如果這四種Javadoc標記出現，描述都不能為空。當從句無法在一行寫完時，應該斷行。延續行在第一行的字符的位置，縮

18、進至少4個字符單位。摘要片段每個類或者成員的JavadoG都是由一個摘要片段開始的。這個片段非常重要。因為它是類或者方法在使用時唯一能看到的文本說明。主要摘要只是一個片段，應該是一個名詞短語或者動詞短語，而不應該是一個完整的句子。不應該以類似于：AcodeFooisa.或Thismethodreturns.這樣的開頭，但是它應該像一個完整的句子一樣使用標點符號。提示：一種常見的錯誤是把單行形式的Javadoc寫成：/*returnthecustomerID*/,這是不對的。應該改為：/*ReturnsthecustomerID.*/。何處應該使用Javadoc至少Javadoc應該應用于所有的public類、public和protect的字段和方法。以下是一些例例外：方法本身已經足夠說明的情況當方法本身很顯而易見時，不需要Javadoo例如：getFoo。沒有必要加上Javadoc說明"Returnsthefoo。"單元測試中的方法基本都能通過方法名，顯而易見地知道方法的作用。因此不需要增加Javad