中央研究院Java編程規(guī)范.doc

卷號卷號 卷內(nèi)編號卷內(nèi)編號 密級密級 中央研究院中央研究院 Java 編程規(guī)范編程規(guī)范 Version 2 0 作者 Administrator 分類 COD 使用者 設(shè)計員 實 施員 托普集團 2009 文檔信息文檔信息 標(biāo)題 中央研究院 Java 編程規(guī)范 作者 Administrator 創(chuàng)建日期 2009 03 26 上次更新日期 2010 12 22 版本 2 0 部門名稱 中央研究院 文檔狀態(tài)文檔狀態(tài) 文檔狀態(tài) 草稿 正式 文檔評審人 員 SEPG評審時間2001 9 30 修訂文檔歷史記錄修訂文檔歷史記錄 日期日期版本版本說明說明作者作者 2001 9 4初稿張瑋 2001 09 171 0張瑋 2001 09 302 0張瑋 I 目錄目錄 1 簡介簡介 1 1 1目的 1 1 2范圍 1 1 3定義 首字母縮寫詞和縮略語 1 1 4參考資料 1 1 5概述 1 1 6原則 1 1 6 1便于閱讀 2 1 6 2與工具集成 2 1 6 2 1 JavaDoc 2 1 6 2 2 Rose 2 1 6 2 3 配置工具 2 1 6 2 4 編碼工具 2 1 6 3便于調(diào)試 2 1 6 4便于寫作 2 1 6 5減少重復(fù) 2 2 程序設(shè)計標(biāo)準(zhǔn)程序設(shè)計標(biāo)準(zhǔn) 3 2 1通用命名約定 3 2 1 1采用該領(lǐng)域的術(shù)語 3 2 1 2大小寫 3 2 1 3使用可以準(zhǔn)確說明的英文描述符 3 2 1 4下劃線的使用 3 2 1 5避免使用長名字 3 2 1 6標(biāo)識符的命名 3 2 1 7界面元素的命名 4 2 1 8非強制的一些命名規(guī)則 5 2 2通用格式 5 2 2 1圓括號 5 2 2 2縮進 5 2 2 3空白行 5 2 2 3 1 包和引入之間加一個空行 5 2 2 3 2 不同可見性的變量定義之間加一個空行 5 2 2 3 3 方法定義之間加一個空行 5 2 2 3 4 不同可見性的方法組定義之間多加一個空行 5 2 2 4空格 5 2 2 5行寬 6 2 2 6折行 6 2 2 6 1 在分號處折行 6 2 2 6 2 在操作符前折行 6 2 2 6 3 有多個可以選擇的地方時 選擇層次較高的進行折行 6 2 2 6 4 將新行與上一行的同一級的表達式的開始處對齊 6 II 2 2 6 5 方法定義的折行 6 2 2 6 6 簡單地縮進一級 7 2 3注釋 7 2 3 1Java 注釋語句類型 7 2 3 2快速瀏覽 javadoc 8 2 3 3按目的分的注釋類型 9 2 3 3 1 業(yè)務(wù)邏輯注釋 9 2 3 3 2 外部注釋 9 2 3 3 3 變量注釋 9 3 源文件內(nèi)容源文件內(nèi)容 9 3 1文件頭注釋部分 9 3 1 1文件名 10 3 1 2版本信息 10 3 1 3變更記錄 10 3 1 4版權(quán)聲明 10 3 2包及引入部分 10 3 3類及接口定義部分 10 3 3 1變量定義 10 3 3 1 1 位置 10 3 3 1 2 格式 11 3 3 2方法定義 11 3 3 2 1 方法說明 11 3 3 2 1 1 成員函數(shù)做什么以及它為什么做這個 11 3 3 2 1 2 如何在適當(dāng)情況下調(diào)用方法的例子 11 3 3 2 1 3 可用的前提條件和后置條件 11 3 3 2 2 param 12 3 3 2 3 return 12 3 3 2 4 bug 12 3 3 2 5 exception 12 3 3 3語句 12 3 3 3 1 業(yè)務(wù)邏輯注釋 12 3 3 3 1 1 控制結(jié)構(gòu) 12 3 3 3 1 2 代碼做了些什么以及為什么這樣做 代碼做了些什么以及為什么這樣做 12 3 3 3 1 3 局部變量 12 3 3 3 1 4 難或復(fù)雜的代碼 12 3 3 3 1 5 處理順序 13 3 3 3 2 單語句 13 3 3 3 3 復(fù)合語句 13 3 3 3 4 return 語句 13 3 3 3 5 if 語句 13 3 3 3 6 for 語句 14 3 3 3 7 while 語句 14 3 3 3 8 do while 語句 14 3 3 3 9 switch 語句 14 3 3 3 10 try catch 語句 14 III 4 與工具的集成與工具的集成 15 4 1ROSE 15 4 2JAVADOC 15 4 3配置工具 15 5 數(shù)據(jù)數(shù)據(jù) 15 6 最佳實踐最佳實踐 15 6 1先寫注釋再寫程序 15 6 2在文檔注釋中加入 HTML 標(biāo)記 15 6 3盡量在源文件的主類中加入MAIN方法 16 6 4對每種類型的類寫出一個模板 16 6 5盡量不要使用公共的類變量 16 6 6使用 TYPE ARRAYNAME而不要使用 TYPE ARRAYNAME 16 6 7對于對象的比較慎用 使用 OBJECT EQUALS 方法 16 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 1 中央研究院中央研究院 Java 編程規(guī)范編程規(guī)范 1 簡介簡介 本文提供一整套編寫高效可靠的 Java 代碼的標(biāo)準(zhǔn) 約定和指南 它們以安全可 靠的軟件工程原則為基礎(chǔ) 使代碼易于理解 維護和增強 而且 通過遵循這些程序 設(shè)計標(biāo)準(zhǔn) 你作為一個 Java 軟件開發(fā)者的生產(chǎn)效率會有顯著提高 經(jīng)驗證明 若從 一開始就花時間編寫高質(zhì)量的代碼 則在軟件開發(fā)階段 對代碼的修改要容易很多 最后 遵循一套通用的程序設(shè)計標(biāo)準(zhǔn)將帶來更大的一致性 使軟件開發(fā)團隊的效率明 顯提高 1 1目的目的 本文檔用于指導(dǎo)編碼 并確立起一個易于理解 維護 并同軟件過程及過程工具 緊密集成的編碼約定 1 2范圍范圍 本文檔對中央研究院所有采用 Java 作為開發(fā)語言的項目適用 1 3定義 首字母縮寫詞和縮略語定義 首字母縮寫詞和縮略語 注釋率注釋在代碼中所占比例 語句 注釋在源文件中 C 語言風(fēng)格注釋 行內(nèi)注釋 文檔注釋 1 4參考資料參考資料 RUP2000 中文版的 Java 編程指南 Draft Java Coding Standard Doug Lea Javasoft coding standards The Infospheres Java Coding Standard 1 5概述概述 本文檔共分為六部分 第一部分為簡介 第二部分程序設(shè)計的一些普遍標(biāo)準(zhǔn) 為 第三部分為對 Java 源文件的分結(jié)構(gòu)說明 第四部分為描述與工具的集成 第五部分為本文檔所規(guī)定的一些數(shù)據(jù) 第六部分為建議的最佳實踐 1 6原則原則 本節(jié)描述描述制作本文檔時所采取的原則 這些原則是一開始就確定的 并且貫 穿在整個文檔中 以下的原則的排列是按優(yōu)先級進行的 這也就是說 在原則之間有 沖突時 應(yīng)該優(yōu)先考慮排在前面的項目 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 2 1 6 1便于閱讀 從軟件工程的角度上來看 代碼讓人更容易看懂遠比讓機器看懂更有價值得多 首先代碼永遠不進行維護似乎是很少發(fā)生的 其次 就算代碼永遠不進行維護 至少 為了代碼重用的目的也需要其他人能夠很容易地看懂代碼 這里有一條 30 秒原則 即其他程序員能在 30 秒內(nèi)完全讀懂你的方法 理解做什么 為什么及怎樣做的 1 6 2與工具集成 鑒于開發(fā)過程大量地集成了工具 因此要與整個開發(fā)過程結(jié)合就必須考慮怎樣使 代碼與工具和平相處并配合密切 與工具集成同時可以增加生產(chǎn)力 并減少由于人工 轉(zhuǎn)換過程中引入的錯誤 1 6 2 1 JavaDoc 與 JavaDoc 的集成可使文檔的說明自動生成并可表現(xiàn)為多種形式 1 6 2 2 Rose 考慮到整個開發(fā)過程使用了 RUP 因此與其所提供的工具 Rose 的集成是很有價 值的 與 Rose 的集成是指保存在 Rose 中的設(shè)計模型可正向生成符合本規(guī)范的代碼 也可從符合本規(guī)范的代碼中反向生成 Rose 的設(shè)計模型 1 6 2 3 配置工具 與配置工具的集成是指代碼規(guī)范與配置工具的要求不沖突 1 6 2 4 編碼工具 與編碼工具的集成是指代碼可用編碼工具自動完成一部分內(nèi)容 這也是提高生產(chǎn) 力的一種努力 1 6 3便于調(diào)試 便于調(diào)試是指在規(guī)范的約束下 應(yīng)該不影響調(diào)試 1 6 4便于寫作 這條原則是說明不要花時間去進行格式的編排 如將注釋換一行書寫 而不是花 時間去調(diào)整讓注釋右對齊 讓實施員集中精力于該干的事 而諸如注釋的好看與否等 等則不應(yīng)該是編碼人員關(guān)心的事 1 6 5減少重復(fù) 同樣的一個信息不應(yīng)該在多個地方出現(xiàn) 原則原則約定約定 便于閱讀縮進 適當(dāng)?shù)卦黾永ㄌ?折行 行寬限制 與工具集成對 JavaDoc 的注釋支持 對 Rose 的注釋支持 JBuilder 的模板文件及配置 便于調(diào)試一行一條語句 便于寫作注釋與語句不同行 減少重復(fù)同樣的內(nèi)容不在多處重復(fù) 表格 1原則及約定對應(yīng)表 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 3 2 程序設(shè)計標(biāo)準(zhǔn)程序設(shè)計標(biāo)準(zhǔn) 本節(jié)的大部分內(nèi)容是從參考資料 1 中剪裁而來 如果需要更詳細的內(nèi)容 請參見 參考資料 1 中的程序設(shè)計標(biāo)準(zhǔn)的一節(jié) Java 的程序設(shè)計標(biāo)準(zhǔn)很重要 原因在于它將提高開發(fā)團隊各成員的代碼的一致性 一致性的提高會使代碼更易理解 這意味著它更易開發(fā)和維護 從而降低了應(yīng)用程序 的總開發(fā)成本 2 1通用命名約定通用命名約定 我們將在整個標(biāo)準(zhǔn)中討論命名約定 所以讓我們先討論幾個基本點 2 1 1采用該領(lǐng)域的術(shù)語 如果用戶稱他們的 客戶 clients 為 顧客 customers 那么就采用術(shù)語 Customer 來命名這個類 而不用 Client 許多程序開發(fā)者會犯的一個錯誤是 不去使 用工業(yè)或領(lǐng)域里已經(jīng)存在著很完美的術(shù)語時 卻生造出一些普通詞匯 2 1 2大小寫 常量的字母全部大寫 單詞之間用一個下劃線字符 進行分隔 除常量外的命名采用大小寫混合 提高名字的可讀性 一般采用小寫字母 但是 類和接口的名字的首字母 以及任何中間單詞的首字母應(yīng)該大寫 2 1 3使用可以準(zhǔn)確說明的英文描述符 例如 采用類似 firstName grandTotal 或 CorporateCustomer 這樣的名字 雖 然象 x1 y1 或 fn 這樣的名字很簡短 輸入起來容易 但是我們難以知道它們代表什 么 結(jié)果是什么含義 因而使代碼難以理解 維護和改進 2 1 4下劃線的使用 避免使用下劃線作為名字的首末字母 以下劃線為首末字母的名字通常為系統(tǒng)保 留 除預(yù)處理定義之外 一般不用作用戶命名 更重要的是 下劃線經(jīng)常造成麻煩而 且難輸入 所以盡量避免使用 因此建議下劃線只用在常量的命名的單詞中間作分隔 符 2 1 5避免使用長名字 命名不要超過標(biāo)識符最大字符數(shù) 標(biāo)識符字符數(shù)請參見數(shù)據(jù)一節(jié) 雖然 PhysicalOrVirtualProductOrService 看起來似乎是個不錯的類名 但是這個 名字太長了 應(yīng)該考慮重新給它起個短一點的名字 比如象 Offering 2 1 6標(biāo)識符的命名 標(biāo)識符類型標(biāo)識符類型 命名規(guī)則命名規(guī)則Examples Packages 每一個包的名稱總是小寫 規(guī)則采用類似于 TCP IP 中域名的反序 即以 com edu gov mil net org 或 ISO 3166 1981 中定義的兩位 國家代碼開始 接著是組織名稱 在此處以 com topgroup 開始 接著是 其后的部分由項目自已定義 com topgroup eng com topgroup report v2 com topgroup jdm Classes 類名必須是名詞 大小寫遵照前面定義的大小 class Raster 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 4 標(biāo)識符類型標(biāo)識符類型 命名規(guī)則命名規(guī)則Examples 寫規(guī)則 即每個單詞首字母大寫 類名應(yīng)該 簡單清晰 不要使用除通用的計算機縮寫或通 用的領(lǐng)域縮寫外的其它縮寫 class ImageSprite Interfaces 同類名規(guī)則 interface RasterDelegate interface Storing Methods 方法應(yīng)該是動詞 或以動詞開始的動賓結(jié)構(gòu)短 語 大小寫遵照前面定義的大小寫規(guī)則 即除 第一個單詞外 每個單詞的首字母大寫 run runFast getBackground Variables 變量名應(yīng)該短而準(zhǔn)確并便于記憶 大小寫遵照 前面定義的大小寫規(guī)則 即除第一個單詞外 每個單詞的首字母大寫 除了臨時使用的如 循環(huán)變量等以外 不要使用單字符的變量名 對于使用單字符的臨時變量名 建議循環(huán)變量 名用 i j k n 表示整數(shù) c d e 表示字符 int i char c float myWidth Constants 全部大寫 單詞之間用下劃線分隔 static final int MIN WIDTH 4 static final int MAX WIDTH 999 static final int GET THE CPU 1 2 1 7界面元素的命名 界面元素是指如 Form 控件等變量及類的命名 界面元素命名的一條基本原則 是界面元素的命名應(yīng)簡單而不產(chǎn)生混淆 一般情況下 界面元素的命名直接參照變量 命名規(guī)則 但若發(fā)生了混淆或估計會發(fā)生混淆的界面元素 則可以在該元素的后加元 素類型的后綴 后綴的生成規(guī)則是 1 若元素類型是標(biāo)準(zhǔn)的 Swing 類型 則去掉類名 J 字符后的部分為元素類型 名 2 若元素類型是標(biāo)準(zhǔn)的 AWT 類型 則直接使用類名 3 如果元素類型不是標(biāo)準(zhǔn)的 Swing 或 AWT 類型 元素類型的后綴使用其 Swing 或 AWT 的基類進行命名 如 自定義了 class MyPanel extends JPanel 則若有 MyPanel 的元素 則元素后綴為 Panel 下表給出了基本的元素類型后綴 類型類型后綴后綴例例 JPanelPanellistPanel JButtonButtondelButton JFrameFramemainFrame JInternalFrameFrame 或 InternalFramewelcomeFrame welcomeInternalFrame JCheckBoxCheckBox J 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 5 2 1 8非強制的一些命名規(guī)則 類型類型規(guī)則規(guī)則例例 抽象類以 Abstract 開始 AbstractDjinn AbstractCat AbstractClass AbstractPlayer Factory 類以 Factory 結(jié)束 DjinnFactory CatFactory ClassFactory PlayerFactor 實現(xiàn)類以 Impl 結(jié)束 DjinnImpl CatImpl ClassImpl PlayerImpl Exception以 Exception 結(jié)束 DjinnException CatException ClassException PlayerException Interface以 Interface 結(jié)束或加 able 后綴 DjinnInterface CatInterface Runnable RemoteLoadable 2 2通用格式通用格式 一種提高代碼可讀性的方法是給代碼分段 換句話說 就是在代碼塊內(nèi)讓代碼縮 進 所有在括號 和 之內(nèi)的代碼 構(gòu)成一個塊 基本思想是 塊內(nèi)的代碼都應(yīng)統(tǒng)一地 縮進去一個單位 2 2 1圓括號 在表達式 方法調(diào)用及方法聲明中圓括號 后及 前不應(yīng)該有空格 2 2 2縮進 同級之間在同一個縮進位置 下一級與上一級之間需要縮進 每一級縮進空格數(shù)請參見數(shù)據(jù)一節(jié) 2 2 3空白行 在代碼中使用空白 在 Java 代碼中加入幾個空行 也叫空白 將代碼分為一些 小的 容易理解的部分 可以使它更加可讀 建議采用一個空行來分隔代碼的邏輯組 例如控制結(jié)構(gòu) 采用兩個空行來分隔方法定義 沒有空白的代碼很難讀 很難理解 2 2 3 1 包和引入之間加一個空行 2 2 3 2 不同可見性的變量定義之間加一個空行 2 2 3 3 方法定義之間加一個空行 2 2 3 4 不同可見性的方法組定義之間多加一個空行 2 2 4空格 關(guān)鍵字與其后緊挨的括號之間應(yīng)有一個空格進行分隔 參數(shù)列表的逗號之后應(yīng)有一個空格進行分隔 大括號開始之前應(yīng)有一個空格進行分隔 所有的二元操作符的前后均應(yīng)有一個空格 二元操作符的例子有加號 除號 等 于符號 賦值符號等 for 的每一個語句之間應(yīng)有空格 即 for expr1 expr2 expr3 強制類型轉(zhuǎn)換的括號之后應(yīng)有一個空格 如 myMethod byte aNum Object x myMethod int cp 5 int i 3 1 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 6 2 2 5行寬 行寬不得超過最大行寬 超過最大行寬就需要折行 最大行寬請參見數(shù)據(jù)一節(jié) 原理 行寬超過最大行寬往往需要用橫向滾動條 影響閱讀 而最大行寬之內(nèi)的字符數(shù)在大 多數(shù)閱讀器中均能方便地進行閱讀及打印 2 2 6折行 當(dāng)一行裝不下內(nèi)容時 需要對這些內(nèi)容進行折行 折行時遵守以下規(guī)則 2 2 6 1 在分號處折行 2 2 6 2 在操作符前折行 操作符包括 左括號 逗號 var someMethod1 longExpression1 someMethod2 longExpression2 longExpression3 2 2 6 3 有多個可以選擇的地方時 選擇層次較高的進行折行 同一層次是指在表達式樹中同一級 同一個括號內(nèi) 層次較高是指在表達式樹 中較高的一級 以下兩個例子可以說明這個規(guī)則 longName1 longName2 longName3 longName4 longName5 4 longname6 PREFER longName1 longName2 longName3 longName4 longName5 4 longname6 AVOID 2 2 6 4 將新行與上一行的同一級的表達式的開始處對齊 此處同一級的含義同上 2 2 6 5 方法定義的折行 如果方法定義太長 可以在參數(shù)處進行折行 下一行可以遵守同級開始處對齊原 則 如 同級開始處對齊原則 someMethod int anArg Object anotherArg String yetAnotherArg Object andStillAnother 比上一行縮進一級原則 private static synchronized horkingLongMethodName int anArg Object anotherArg String yetAnotherArg Object andStillAnother 2 2 6 6 簡單地縮進一級 在使用以上原則時 如果出現(xiàn)太深的縮進 如括號開始處可能在行末附近 這時 只是簡單地在上一行的開始處縮進一級 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 7 2 3注釋注釋 2 3 1Java 注釋語句類型 Java 有三種注釋語句風(fēng)格 以 開始 結(jié)束的文檔注釋 以 開始 以 結(jié) 束的 C 語言風(fēng)格注釋 以及以 開始 代碼行末尾結(jié)束的單行注釋 下表是對各 類注釋語句建議用法的一個概括 也給出了幾個例子 注釋語句類型注釋語句類型用法用法示例示例 文檔注釋在接口 類 方法和字段 聲明之前緊靠它們的位置 用文檔注釋進行說明 文 檔注釋由 javadoc 處理 為一個類生成外部注釋文 檔 如下所示 Customer 顧客 顧客是 指作為我們的服務(wù)及產(chǎn)品 的銷售對象的任何個人或 組織 author S W Ambler C 語言風(fēng)格注釋采用 C 語言風(fēng)格的注釋語 句將無用的代碼注釋掉 保留這些代碼是因為用戶 可能改變想法 或者只是 想在調(diào)試中暫時不執(zhí)行這 些代碼 這部分代碼已被它前面的 代碼替代 所以于 1999 年 6 月 4 日被 B Gustafsson 注釋掉 如果 兩年之后仍未用這些代碼 將其刪除 源代碼 單行注釋在方法內(nèi)部采用單行注釋 語句對業(yè)務(wù)邏輯 代碼片 段和臨時變量聲明進行說 明 因為讓利活動 從 1995 年 2 月開始 所以給所有超過 1000 的 發(fā)貨單 5 的折扣 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 8 2 3 2快速瀏覽 javadoc Sun 公司的 Java Development Kit JDK 中有一個名為 javadoc 的程序 它可以 處理 Java 的源代碼文件 并且為 Java 程序產(chǎn)生 HTML 文件形式的外部注釋文檔 Javadoc 支持一定數(shù)目的標(biāo)記 標(biāo)識注釋文檔中各段起始位置的保留字 詳情請參考 JDK javadoc 文檔 本規(guī)范支持并且要求有 Javadoc 的注釋標(biāo)記 該標(biāo)記可由工具自動生成也可由手 工制作 標(biāo)記標(biāo)記用于用于目的目的 author name類 接口 說明特定某一段程序代碼的作者 每一個作者各有一個標(biāo)記 deprecated類 方法 說明該類的應(yīng)用程序編程接口 API 已被廢棄 因此應(yīng)不再使用 exception name description 方法說明由方法發(fā)出的異常 一個異 常采用一個標(biāo)記 并要給出異常 的完整類名 param name description 方法用來說明傳遞給一個方法的參數(shù) 其中包括參數(shù)的類型 類和用法 每個參數(shù)各有一個標(biāo)記 return description方法若方法有返回值 對該返回值進 行說明 應(yīng)說明返回值的類型 類 和可能的用途 since類 方法說明自從有 JDK 1 1 以來 該項 已存在了多長時間 see ClassName類 接口 方法 字段 在文檔中生成指向特定類的超文 本鏈接 可以并且應(yīng)該采用完全 合法的類名 see ClassName member functionName 類 接口 方法 字段 在文檔中生成指向特定方法的超 文本鏈接 可以并且應(yīng)該采用完 全合法的類名 version text類 接口說明特定一段代碼的版本信息 2 3 3按目的分的注釋類型 注釋可按其目的分為外部注釋 業(yè)務(wù)邏輯注釋及其它注釋 業(yè)務(wù)邏輯注釋是指在 類的方法中用于解釋業(yè)務(wù)邏輯的注釋 外部注釋是指不在類的方法中 是用于對外解 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 9 釋類或類的接口的注釋 變量注釋是指不用于外部注釋中 對局部變量或私有類變量 等變量的注釋 2 3 3 1 業(yè)務(wù)邏輯注釋 在代碼塊 如類的方法 靜態(tài)方法等 中用于解釋業(yè)務(wù)邏輯的注釋稱為業(yè)務(wù)邏輯 注釋 除特殊情況外 業(yè)務(wù)邏輯注釋一般采用單行注釋的方式 代碼數(shù) 代碼數(shù)即語句數(shù) 不包括變量定義 與代碼行數(shù)不同 代碼數(shù)可用自動 化工具獲得 注釋數(shù)為針對于語句的注釋數(shù) 注釋數(shù)與注釋的行數(shù)不同 在兩條語句之間的注 釋 不管行數(shù)多少 都算作一個注釋 注釋率 注釋數(shù) 代碼數(shù) 100 每個方法的注釋率的下限請參見數(shù)據(jù)一節(jié) 但語句數(shù)少于 3 句的除外 2 3 3 2 外部注釋 不在代碼塊中 用于對外解釋類或類的接口的注釋稱為外部注釋 外部注釋包括 類的內(nèi)容注釋 公共方法及變量注釋 保護方法及變量注釋 包方法及變量注釋 除 非特殊情況 外部注釋最好采用內(nèi)容注釋的方式 外部注釋的注釋率 內(nèi)容注釋數(shù) 定義數(shù) 100 其中定義數(shù)是指公用的類或類的接口的數(shù)量 外部注釋的注釋率的下限請參見數(shù)據(jù)一節(jié) 如為 100 則每一個公共的 保護 的 包的方法和變量都應(yīng)加一個內(nèi)容注釋 原理 每一個公共 保護及包方法及變量都可能被其它人用到 因此關(guān)于該項的說明必須有 2 3 3 3 變量注釋 不用于外部注釋中 對局部變量或私有類變量等變量的注釋稱為變量注釋 變量 注釋的注釋率 注釋數(shù) 變量數(shù) 100 變量注釋的注釋率的下限請參見數(shù)據(jù)一節(jié) 3 源文件內(nèi)容源文件內(nèi)容 每個 Java 源文件只包含一個公共的類或接口 這是 Sun 公司的規(guī)定 當(dāng)該公共 類附帶有私有類或接口時 可以把它們放在該公共類的同一個文件 但公共類必須出 現(xiàn)在它們前面 源文件由以下三部分組成 文件頭注釋部分 包及引入部分 類及接口定義部分 3 1文件頭注釋部分文件頭注釋部分 每個 Java 源文件必須以一個 C 語言風(fēng)格的注釋開始 該注釋包括文件名 版本 信息 日期 變更記錄及版權(quán)聲明 參考格式如下 Version information Date 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 10 Copyright notice 3 1 1文件名 記錄源文件名 不包括路徑 3 1 2版本信息 版本信息可選 但如果有的話 必須與配置系統(tǒng)的版本信息兼容 3 1 3變更記錄 變更記錄包含變更日期 變更人和變更內(nèi)容 3 1 4版權(quán)聲明 版權(quán)聲明是必須的 其內(nèi)容必須包括 公司 年份 可用如下格式 Copyright 2000 2001 Topgroup All Rights Reserved 3 2包及引入部分包及引入部分 Java 源文件的第一條非注釋行為 package 語句 包后加一空行 之后可以是一 個或多個 import 語句 例如 package java awt import java awt peer CanvasPeer 3 3類及接口定義部分類及接口定義部分 類及接口定義部分開始于一個內(nèi)容注釋以說明類及接口的功能 環(huán)境 使用方法 等說明 類或接口與類或接口之間用一個空行間隔 3 3 1變量定義 變量定義包括類變量定義及局部變量定義 3 3 1 1 位置 這兩種變量定義都應(yīng)該在其任用域的一開始處定義 即對于類變量 在類的開始 處的大括號之后就對它進行定義 對于方法內(nèi)的局部變量 在方法定義開始處的大括 號之后進行定義 盡量不要在方法內(nèi)某一塊中定義局部變量 靜態(tài)變量在最前 按可見性從高到低排列 若有靜態(tài)塊 則靜態(tài)塊在其后 其后 是非靜態(tài)的類變量 按可見性從高到低排列 即按公共 保護 包 私有的順序進行 排列 不同可見性的類變量組之間應(yīng)用一個空行進行分隔 3 3 1 2 格式 公共的類變量前必須有一個內(nèi)容注釋說明它 公共的類變量前必須有一個內(nèi)容注釋說明它 每個變量定義應(yīng)該占據(jù)一行每個變量定義應(yīng)該占據(jù)一行 并且應(yīng)該對該變量進行注釋 但建議不要進行行尾 注釋 最好在變量定義之前進行注釋 如 indentation level 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 11 int level size of table int size 就好于 int level size 兩個同樣可見性的變量定義之間不要有空行兩個同樣可見性的變量定義之間不要有空行 類型不同的變量不要在同一行中類型不同的變量不要在同一行中 如 int foo fooarray 避免 盡量在定義處對變量進行初始化盡量在定義處對變量進行初始化 3 3 2方法定義 兩個方法定義之間用一個空行分隔兩個方法定義之間用一個空行分隔 方法名與參數(shù)引導(dǎo)符圓括號之間不要有空格方法名與參數(shù)引導(dǎo)符圓括號之間不要有空格 方法順序為 構(gòu)造方法 finalize 方法 初始化方法 static 方法 公共方法 保護方法 包方法 私有方法 方法定義部分開始于一個內(nèi)容注釋方法定義部分開始于一個內(nèi)容注釋以說明該方法的功能 環(huán)境 使用方法等所有 重要的有助于理解方法的信息 盡可能在其中加入 Javadoc 標(biāo)記 當(dāng)然 這件事有一 部分也可能是由設(shè)計人員完成的 有返回值的必須加 return 標(biāo)記 有參數(shù)的必須對 每一個參數(shù)加 param 標(biāo)記 有錯誤的必須加 exception 標(biāo)記 盡量加 see 標(biāo)記 這些信息包含但不僅僅局限于以下內(nèi)容 3 3 2 1 方法說明 方法說明對方法整體進行說明 包括以下內(nèi)容 3 3 2 1 1 成員函數(shù)做什么以及它為什么做這個 通過給一個方法加注釋 讓別人更加容易判斷他們是否可以復(fù)用代碼 注釋出方 法為什么做這個可以讓其他人更容易將你的代碼放到程序的上下文中去 也使其他人 更容易判斷是否應(yīng)該對你的某一段代碼加以修改 有可能他要做的修改與你最初為什 么要寫這一段代碼是相互沖突的 3 3 2 1 2 如何在適當(dāng)情況下調(diào)用方法的例子 最簡單的確定一段代碼如何工作的方法是看一個例子 考慮包含一到兩個如何調(diào) 用方法的例子 3 3 2 1 3 可用的前提條件和后置條件 前提條件是指一個方法可正確運行的限制條件 后置條件是指一個方法執(zhí)行完以 后的屬性或聲明 前提條件和后置條件以多種方式說明了在編寫方法過程中所做的假 設(shè) 精確定義了一個方法的應(yīng)用范圍 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 12 3 3 2 2 param 如果帶參數(shù) 那么什么樣的參數(shù)必須傳給方法 以及方法將怎樣使用它們 原理 這個信息使其他程序員了解應(yīng)將怎樣的信息傳遞給一個方法 在 快速瀏覽 javadoc 中討論的 javadoc param 標(biāo)識便用于該目的 3 3 2 3 return 如果方法有返回值 則應(yīng)注釋出來 原理 這樣可以使其他程序員正確地使用返回值 對象 在 快速瀏覽 javadoc 里討論的 javadoc return 標(biāo)識便用于此目的 3 3 2 4 bug 方法中的任何突出的問題都應(yīng)說明 原理 以便讓其他程序開發(fā)者了解該方法的弱點和難點 如果在一個類的多個方法中都存在 著同樣的問題 那么這個問題應(yīng)該寫在類的說明里 3 3 2 5 exception 應(yīng)說明方法拋出的所有異常 原理 以便使其他程序員明白他們的代碼應(yīng)該捕獲些什么 在 快速瀏覽 javadoc 中討論 的 javadoc exception 標(biāo)識便用于此目的 3 3 3語句 3 3 3 1 業(yè)務(wù)邏輯注釋 除方法注釋以外 在方法內(nèi)部還需加上注釋語句來說明你的工作 目的是使方法 更易理解 維護和增強 建議對業(yè)務(wù)邏輯采用單行注釋 因為它可用于整行注釋和行末注釋 采用 C 語言 風(fēng)格的注釋語句去掉無用的代碼 因為這樣僅用一個語句就可以容易地去掉幾行代碼 此外 因為 C 語言風(fēng)格的注釋語句很象文檔注釋符 它們之間的用法易混淆 這樣會 使代碼的可理解性降低 所以 應(yīng)盡量減少使用它們 在方法內(nèi) 一定要說明 3 3 3 1 1 控制結(jié)構(gòu) 說明每個控制結(jié)構(gòu) 例如比較語句和循環(huán) 你無須讀完整個控制結(jié)構(gòu)內(nèi)的代碼才 判斷它的功能 而僅需看看緊靠它之前的一到兩行注釋即可 3 3 3 1 2 代碼做了些什么以及為什么這樣做 代碼做了些什么以及為什么這樣做 通常你常能看懂一段代碼做了什么 但對于那些不明顯的代碼 你很少能判斷出 它為什么要那樣做 例如 看完一行代碼 你很容易地就可以斷定它是在定單總額上 打了 5 的折扣 這很容易 不容易的是為什么要打這個折扣 顯然 肯定有一條商 業(yè)法則說應(yīng)打折扣 那么在代碼中至少應(yīng)該提到那條商業(yè)法則 這樣才能使其他開發(fā) 者理解你的代碼為什么會是這樣 3 3 3 1 3 局部變量 在一個方法內(nèi)定義的每一個局部變量都應(yīng)采用一個注釋說明它的用法 3 3 3 1 4 難或復(fù)雜的代碼 若發(fā)現(xiàn)不能或者沒有時間重寫代碼 那么應(yīng)將方法中的復(fù)雜代碼詳細地注釋出來 一般性的經(jīng)驗法則是 如果代碼并非顯而易見的 則應(yīng)說明 3 3 3 1 5 處理順序 如果代碼中有的語句必須在一個特定的順序下執(zhí)行 則應(yīng)保證將這一點注釋出來 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 13 沒有比下面更糟糕的事了 你對一段代碼做一點簡單的改動 卻發(fā)現(xiàn)它不工作 于是 花了幾個小時查找問題 最后發(fā)現(xiàn)原來是搞錯了代碼的執(zhí)行順序 在閉括號后加上注釋 在閉括號后加上注釋 常常會發(fā)現(xiàn)你的控制結(jié)構(gòu)內(nèi)套了一個控制結(jié)構(gòu) 而在這個 控制結(jié)構(gòu)內(nèi)還套了一個控制結(jié)構(gòu) 雖然應(yīng)該盡量避免寫出這樣的代碼 但有時你發(fā)現(xiàn) 最好還是要這樣寫 原理 問題是閉括號 應(yīng)該屬于哪一個控制結(jié)構(gòu)這一點就變得混淆了 一個好消息是 有一 些編輯器支持一種特性 當(dāng)選用了一個開括號后 它會自動地使相應(yīng)得閉括號高亮顯示 一個壞 消息是 并非所有的編輯器都支持這種屬性 將類似 end if end for end switch return myDisk size return size size defaultSize 3 3 3 5 if 語句 if 語句采用下列格式 if condition statements if condition statements else statements if condition statements else if condition statements 中央研究院 Java 編程規(guī)范 6ffefdbb3a4f3ef85ad8d6abba53c88c pdfPage 14 else statements 3 3 3 6 for 語句 for 語句采用下列格式 for initialization condition update statements 3 3 3 7 while 語句 while 語句采用下列格式 while condition statements 3 3 3 8 do while 語句 do while 語句采用下列格式 do statements while condition 3 3 3 9 switch 語句 switch 語句采用下列格式 switch condition case ABC statements falls through case DEF statements break case XYZ statements break default statements break 3 3 3 10 try catch 語句 try catch 語句采用下列格式 try statem