項目指導(dǎo)書(第一學期).doc

目錄 項目案例1應(yīng)用場景1項目基本需求描述1項目運行環(huán)境2文檔范例4開發(fā)文檔5項目任務(wù)書5項目進展報告（每個階段提交一份報告）5個人變更記錄5用戶界面檢查表6軟件總體設(shè)計文檔8測試計劃11測試報告12Java編碼規(guī)范131 介紹(Introduction)132 文件名(File Names)133 文件組織(File Organization)144 縮進排版(Indentation)155 注釋(Comments)176 聲明(Declarations)207 語句(Statements)228 空白(White Space)259 命名規(guī)范(Naming Conventions)2610 編程慣例(Programming Practices)2711 代碼范例(Code Examples)29項目案例 應(yīng)用場景 當今社會，網(wǎng)絡(luò)技術(shù)越來越發(fā)展，可以說，二十一世紀就是網(wǎng)絡(luò)的世紀。網(wǎng)絡(luò)迅猛發(fā)展，勢不可擋。為了實現(xiàn)資源共享，各式各樣的網(wǎng)站發(fā)展迅速，各種各樣的聊天工具不斷更新。某公司希望通過一個聊天工具加強員工和客戶之間的溝通和交流。所以制作一個聊天室勢在必行。為了實現(xiàn)一個更好的網(wǎng)絡(luò)交互平臺，各用戶之間能夠?qū)崟r方便的傳遞信息，按照用戶對系統(tǒng)的要求不同，可以在聊天室里實現(xiàn)公共聊天，也可以邀幾個私交好友私聊，同時提供了兩個用戶之間能夠傳送文件。本系統(tǒng)是基于方便用戶聊天，傳遞信息，共享資源，所以系統(tǒng)的功能主要是從以上幾個模塊著手。本項目主要是利用JAVA語言制作一個聊天室,采用的是客戶/服務(wù)器. 二層的C/S結(jié)構(gòu)是指以單一的服務(wù)器和局域網(wǎng)為核心，能通過客戶端與用戶進行直接對話。主要有二大功能：一是它用于檢查用戶從鍵盤等輸入的數(shù)據(jù),顯示應(yīng)用輸出的數(shù)據(jù)。為使用戶能直觀地進行操作,一般要使用圖形用戶接口(GUI),操作簡單、易學易用。在變更用戶接口時,只需改寫顯示控制和數(shù)據(jù)檢查程序,而不影響其他。檢查的內(nèi)容也只限于數(shù)據(jù)的形式和值的范圍,不包括有關(guān)業(yè)務(wù)本身的處理邏輯。典型的C/S結(jié)構(gòu)有以下特點：1、服務(wù)器負責數(shù)據(jù)管理及程序處理2、客戶機負責界面描述和界面顯示3、客戶機向服務(wù)器提出處理要求4、服務(wù)器響應(yīng)將處理結(jié)果返回客戶機5、使網(wǎng)絡(luò)數(shù)據(jù)流量最少。項目基本需求描述 根據(jù)上面的項目背景，擬定以下的一些功能需求。1. 用戶注冊 2. 用戶登錄3. 在線用戶列表4. 用戶公聊5. 用戶私聊6. 文件傳遞擴展功能（如果完整實現(xiàn)一個擴展功能，適當加分）：1 可以切換不同的界面風格2 用戶可以更改個人資料，尋找密碼3 表情聊天4 IP地址顯示n 用戶注冊第一次用戶需要提供個人注冊信息，注冊的用戶名不能重復(fù)，密碼長度不能少于6位，個人信息必須提供完整，并且存儲在數(shù)據(jù)庫中。n 用戶登錄用戶輸入用戶名和密碼，提交給將服務(wù)器端的確認，根據(jù)從服務(wù)器中傳過來的確認信息，判斷用戶登錄的情況。如果用戶名和密碼正確的話，則登錄聊天室主界面；如果已經(jīng)在線，則輸出已經(jīng)在線；否則輸出用戶名和密碼錯誤，需要重新登錄或者注冊。n 在線用戶列表用戶登錄之后，需要知道系統(tǒng)中，有哪些用戶在線，這樣可以方便用戶選擇與個別用戶私聊和傳送文件，也可以進行公聊。n 用戶公聊用戶輸入的用戶名和密碼都正確后，則進入聊天室。聊天主界面主要由四大版塊組成：聊天信息、在線用戶列表、系統(tǒng)消息和聊天的一些操作。聊天信息版塊設(shè)計思想：一種就是將客戶的聊天信息寫入數(shù)據(jù)庫，一種是將其寫入向量中。n 用戶私聊如果兩個人聊的話題比較隱秘，不想被其他人看到，就要使用私聊。在這里，如果說話對象是所有人的話，不能選擇私聊；如果從當前用戶列表中選擇了一個用戶之后，則私聊按鈕是可選的。n 文件傳遞兩個用戶在聊天過程中，可能需要相互間傳送文件。象用戶聊天信息和在線用戶這樣一些信息都是保存在服務(wù)器端，然后每個客戶讀取服務(wù)器端向量中的內(nèi)容，此時服務(wù)器與客戶端的聯(lián)系是一對多的，而傳送文件是一對一的。所以直接傳送，不需要經(jīng)過服務(wù)器端保存。項目運行環(huán)境 服務(wù)器軟硬件要求（最低配置）軟件：Windows 2000及以上TCP/IP協(xié)議硬件：CPU: P及以上 內(nèi)存：128M硬盤：4G以上客戶機軟硬件要求軟件：Windows 98/ME/2000及以上TCP/IP協(xié)議硬件：CPU: P及以上內(nèi)存：最少128M硬盤：4G以上文檔范例 n 文檔文檔是計算機編程最重要的方面之一。大多數(shù)已經(jīng)完成了程序編寫、測試和實現(xiàn)的程序員獲得解脫般太過著急地進入下一個項目。另一方面，程序用戶抱怨文檔老是不完整、不精確或者不正確。僅由程序作者調(diào)試程序的情況很少。如果程序沒有輸入/輸出要求、如何執(zhí)行程序、特定部分的代碼做什么之類的詳細信息，那么其他用戶就很難進行程序調(diào)試。因此文檔的目的就是要指導(dǎo)用戶全面了解程序以及如何正確使用它。文檔應(yīng)在哪個階段書寫呢？大多數(shù)情況是在項目結(jié)束時才補上的。結(jié)果，文檔就是些倉促的注解列表，再加上很少的程序運行指導(dǎo)。這個層次所提供的信息不充分，因此項目間的單元測試和檢查的想法將有助于制定一份有效和有用的文檔。n 程序文檔維護計算機程序的主要原因有兩個。第一個是由于我們沒有能力寫出完全沒有錯誤的大型程序所產(chǎn)生的后果；也就是程序bug的定位和改正。錯誤檢測在許多情況下是一個貫徹程序整個生命周期的過程。大多數(shù)錯誤在正式的調(diào)試和測試過程中被發(fā)現(xiàn)和改正，然后才認為程序完成了。第二個原因是修改現(xiàn)有程序以適應(yīng)規(guī)范的改變。必須修改程序才能滿足不斷變化的用戶需求，才能對程序進行完善。要滿足程序文檔標準，保留用指定詳細信息更新過的每個單元的注釋頁對程序員而言非常有用，這使得項目文檔任務(wù)變得非常容易。n 項目文檔文檔是團隊工作的一個重要方面。對于將可重用性作為首要益處的面向?qū)ο蠓椒ǘ愿侨绱?。?chuàng)建者對一個通用類所作的任何修改應(yīng)該立即寫入文檔，這樣該類的用戶就能注意到。應(yīng)對文檔進行更好的文字處理和適當歸檔。文檔結(jié)構(gòu)應(yīng)該包括：n 封面頁，應(yīng)具有項目名稱、項目小組成員名字及他們的批號和注冊號、提交日期、總頁數(shù)（每頁文檔都要有頁碼）。n 問題陳述的簡要描述。n 分析和設(shè)計，這需要E/R圖、類定義和具有有意義字段名的表結(jié)構(gòu)。n 用于測試的樣本數(shù)據(jù)和程序清單。所有這些信息以及新的程序描述和任何有益于程序理解的其它注釋都應(yīng)整理并添加到文檔文件中，這樣就能對接管該程序或項目且必須重新理解其工作機制的其他人提供幫助。n 參見文檔范例開發(fā)文檔 項目任務(wù)書 Java聊天室系統(tǒng)項目的任務(wù)進度計劃任務(wù)名稱工作人員工作時間任務(wù)描述需求分析開發(fā)組2007年7月29日2007年7月31日根據(jù)用戶提出的需求，制訂比較詳細的需求分析報告文檔系統(tǒng)設(shè)計開發(fā)組2007年8月1日2007年8月4日項目進展報告（每個階段提交一份報告） 項目進展報告項目名稱Java聊天室系統(tǒng)項目經(jīng)理報告名稱需求分析報告項目所處階段需求分析階段時間段2007年7月29日2007年7月31日工作總結(jié)經(jīng)過項目組的詳細分析和討論，確定主要功能需求如下：用戶注冊 用戶登錄在線用戶列表用戶公聊用戶私聊文件傳遞問題與對策1. 問題：文件傳送通過點對點還是通過服務(wù)器中轉(zhuǎn)。 對策：文件傳送通過點對點。 原因：個人變更記錄 個人變更記錄所屬項目變更標題變更內(nèi)容說明變更內(nèi)容以及相關(guān)技術(shù)。執(zhí)行人日期用戶界面檢查表 用戶界面檢查表設(shè)計要素重要性檢查項適合于檢查結(jié)果合適性非常重要用戶界面是否與軟件的功能相融洽？用戶界面是否適合于用戶的應(yīng)用環(huán)境？解釋：如果否定的話，意味著用戶不能有效地使用這個軟件，是不可原諒的缺陷。這個缺陷是需求分析錯誤造成的。評審測試容易理解非常重要（1）界面元素有錯別字，或者措詞含糊、邏輯混亂。（2）消息框的提示文字和按鈕在語義上不連貫。（3）確認消息框、告警消息框、通知消息框、過程消息框的風格混淆在一起。解釋：如果出現(xiàn)如此低級的缺陷，說明開發(fā)人員根本沒有把用戶界面放在心上，用戶很反感這種不敬業(yè)的態(tài)度。是不可原諒的缺陷。評審測試重要（1） 對于常用的功能，用戶能否不必閱讀手冊就能使用嗎？（2） 是否所有界面元素提供了充分而必要的提示？（3） 界面結(jié)構(gòu)和工作流程匹配嗎？（4） 提供聯(lián)機幫助嗎？解釋：如果實現(xiàn)上述要求，說明界面的細節(jié)做得很好。評審測試及時反饋信息重要（1） 是否提供進度條、動畫等反映正在進行的比較耗時間的過程？（2） 是否為重要的操作返回必要的結(jié)果信息？解釋：如果否定的話，說明用戶界面不夠?qū)I(yè)。測試防錯處理非常重要（1） 執(zhí)行破壞性的操作之前，是否獲得用戶的確認？（2） 輸入數(shù)據(jù)或者遞交數(shù)據(jù)時，是否進行相應(yīng)的數(shù)據(jù)校驗（檢查數(shù)據(jù)是否合法）（3） 是否根據(jù)用戶的權(quán)限自動隱藏或者禁用某些功能？解釋：如果否定的話，說明開發(fā)人員沒有防錯處理的常識，是不可原諒的缺陷。測試可選是否提供Undo功能用以撤銷不期望的操作？解釋：如果實現(xiàn)該要求，說明界面的細節(jié)做得很好。測試一致性重要（1） 同類的界面元素是否有相同的視感和相同的操作方式？（2） 是否符合廣大用戶使用同類軟件的習慣？解釋：如果否定的話，說明用戶界面不夠?qū)I(yè)。評審測試個性化可選是否在具備必要的“一致性”的前提下，設(shè)計了與眾不同的、讓用戶記憶深刻的界面？解釋：如果實現(xiàn)該要求，說明界面很有創(chuàng)意。評審測試合理布局可選（1） 界面的布局符合軟件的功能邏輯嗎？（2） 界面元素是否在水平或者垂直方向?qū)R？（3） 界面元素的尺寸是否合理？行、列的間距是否保持一致？（4） 是否恰當?shù)乩么绑w和控件的空白，以及分割線條？（5） 窗口切換、移動、改變大小時，界面正常嗎？解釋：如果否定的話，說明用戶界面不夠?qū)I(yè)。評審測試合理色彩重要（1） 界面的色調(diào)是否讓人感到和諧、滿意？（2） 重要的對象是否用醒目的色彩表示？（3） 色彩使用是否符合行業(yè)的習慣？（4） 是否可以讓色盲、色弱人員使用？解釋：如果實現(xiàn)該要求，說明界面細節(jié)很好。評審測試適應(yīng)用戶群體可選（1） 初學者和專家都有合適的方式操作這個界面嗎？（2） 色盲或者色弱的用戶能正常使用該界面嗎？解釋：如果實現(xiàn)該要求，說明界面細節(jié)很好。測試國際化重要（1） 度量單位、日期格式、人的名字等是否讓用戶誤解？（2） 翻譯文字是否地道，是否符合讀者習慣？評審測試最少步驟最高效率重要是否用合理的最少步驟實現(xiàn)常用的操作，獲得高效率？解釋：如果實現(xiàn)該要求，說明界面細節(jié)很好。測試可復(fù)用重要用戶界面的原型、代碼、文檔是否可以被復(fù)用？解釋：如果實現(xiàn)該要求，說明軟件的需求分析、設(shè)計、實現(xiàn)做得很好。開發(fā)團隊內(nèi)部評估軟件總體設(shè)計文檔 0. 文檔介紹0.1 文檔目的與范圍編寫該文檔的目的在于明確java聊天系統(tǒng)的用戶需求，使得軟件開發(fā)人員與用戶對待開發(fā)軟件的需求有統(tǒng)一的、無二義性的認識。該文檔所描述的內(nèi)容，可作為軟件確認測試的依據(jù)。該文檔的讀者為用戶代表、軟件分析人員、開發(fā)管理人員和測試人員。0.2 讀者對象閱讀對象：一般大眾0.3 參考文獻提示：列出本文檔的所有參考文獻（可以是非正式出版物），格式如下：標識符 作者，文獻名稱，出版單位（或歸屬單位），日期參見java聊天室系統(tǒng)需求說明書0.4 術(shù)語與縮寫解釋縮寫、術(shù)語解 釋1. 系統(tǒng)概述提示：（1）說明本系統(tǒng)“是什么”，（2）描述本系統(tǒng)的主要功能。 java聊天室系統(tǒng)是一個基于客戶機/服務(wù)器結(jié)構(gòu)的兩層的聊天室系統(tǒng)，客戶端（前臺）包括用戶注冊，用戶登錄，多人聊天，私聊，發(fā)送附件，傳送文件等，采用JAVA編寫代碼，服務(wù)端（后臺）進行對客戶端信息的各種處理,并使用JDBC訪問數(shù)據(jù)庫。2. 設(shè)計約束提示：（1）需求約束。體系結(jié)構(gòu)設(shè)計人員從需求文檔（如用戶需求說明書和軟件需求規(guī)格說明書）中提取需求約束，例如： 本系統(tǒng)應(yīng)當遵循的標準或規(guī)范 軟件、硬件環(huán)境（包括運行環(huán)境和開發(fā)環(huán)境）的約束 接口/協(xié)議的約束 用戶界面的約束 軟件質(zhì)量的約束，如正確性、健壯性、可靠性、效率（性能）、易用性、清晰性、安全性、可擴展性、兼容性、可移植性等等。（2）隱含約束。有一些假設(shè)或依賴并沒有在需求文檔中明確指出，但可能會對系統(tǒng)設(shè)計產(chǎn)生影響，設(shè)計人員應(yīng)當盡可能地在此處說明。例如對用戶教育程度、計算機技能的一些假設(shè)或依賴，對支撐本系統(tǒng)的軟件硬件的假設(shè)或依賴等。3. 開發(fā)與運行環(huán)境提示：說明本系統(tǒng)應(yīng)當在什么樣的環(huán)境下開發(fā)和運行，有什么強制要求和建議？類別標準配置最低配置開發(fā)環(huán)境測試環(huán)境運行環(huán)境4. 軟件的總體設(shè)計提示： （1）將系統(tǒng)分解為若干子系統(tǒng)，繪制各種結(jié)構(gòu)圖（例如層次結(jié)構(gòu)圖、數(shù)據(jù)流圖），說明各子系統(tǒng)的主要功能。（盡可能簡單明了，但是能夠闡述清楚系統(tǒng)的結(jié)構(gòu)）。（2）說明“如何”以及“為什么”（how and why）如此分解系統(tǒng)。（3）說明各子系統(tǒng)如何協(xié)調(diào)工作，從而實現(xiàn)原系統(tǒng)的功能。4.1 結(jié)構(gòu)圖A在確定本系統(tǒng)的基本結(jié)構(gòu)后，本系統(tǒng)劃分的五個子模塊的功能如下： 注冊模塊 提交用戶注冊信息給服務(wù)器，將服務(wù)器返回的結(jié)果顯示給用戶； 登錄模塊 提交用戶登錄信息給服務(wù)器；根據(jù)服務(wù)器返回的結(jié)果決定用戶是否可以登錄； 聊天實現(xiàn)模塊 發(fā)送消息，附件，文件等信息給服務(wù)器,接收服務(wù)端發(fā)來的信息進行相應(yīng)處理。 后臺服務(wù)模塊接收客房端發(fā)來的各種信息，進行相應(yīng)的處理。 數(shù)據(jù)庫模塊 響應(yīng)服務(wù)器的指令對數(shù)據(jù)庫進行各種查詢或更新操作，將結(jié)果返回給服務(wù)器。5. 軟件體系的面向?qū)ο笤O(shè)計5.1用例圖5.2 類圖類圖一: 注冊 類圖二:登錄 類圖三:聊天 6. 數(shù)據(jù)庫設(shè)計概述6.1 數(shù)據(jù)庫環(huán)境說明提示： 說明所采用的數(shù)據(jù)庫系統(tǒng)，設(shè)計工具，編程工具，有關(guān)配置等6.2 數(shù)據(jù)庫命名規(guī)則提示：說明表、字段等命名規(guī)則6.3 安全性設(shè)計說明提示：考慮用戶密碼、訪問權(quán)限等等E/R圖6.4 表匯總因為系統(tǒng)只需要一張用戶記錄表,所以定義了一個數(shù)據(jù)庫User,在庫中定義了一張表customer,用來存貯用戶信息,以驗證用戶登錄和記錄用戶注冊.l 定義用戶信息表(customer)字段數(shù)據(jù)類型長度能否為空cNamechar10NOT NULLcSexchar30NOT NULLcJobchar20NULLcPasswordchar20NOT NULLvQuestionvarchar20NOT NULLvAnswervarchar30NULLcE_mailchar20NULL7. 用戶界面設(shè)計概述提示：說明界面設(shè)計要素，注意事項，界面原型等。1、注冊界面控制條件值預(yù)期結(jié)果實際結(jié)果結(jié)論整理按鈕“Register”表中沒有同一被點擊插入表中按鈕“ReWrite”None被點擊清除內(nèi)容按鈕“GoOut”None被點擊退出2、登陸界面控制條件值預(yù)期結(jié)果實際結(jié)果結(jié)論整理按鈕”Enter”表中存在并且PassWord正確被點擊進入聊天室，并且名字顯示在標題上按鈕”Register”None被點擊進入注冊界面按鈕”ReWrite”None被點擊清除所填內(nèi)容按鈕”GoOut”None被點擊退出8. 綜合考慮8.1 穩(wěn)定性和可擴展性提示：在“軟件”生命周期內(nèi)，判斷哪些需求是不變的，預(yù)測哪些需求可能發(fā)生的變化。在總體設(shè)計的時候，既要使總體結(jié)構(gòu)穩(wěn)定，又要適應(yīng)需求變化。8.2 性能分析提示：（1）本系統(tǒng)應(yīng)當具備哪些性能指標才能滿足用戶的需求？（2）如何實現(xiàn)性能指標？8.3 復(fù)用和移植提示：（1）本系統(tǒng)復(fù)用了什么東西（說明出處）？如何解決被復(fù)用成果的質(zhì)量問題？（2）本系統(tǒng)中哪些東西是可以被將來的系統(tǒng)復(fù)用的？有什么構(gòu)思？（3）如何使本系統(tǒng)的功能代碼和用戶界面代碼區(qū)分開來8.4 防錯與出錯處理提示：（1）如何預(yù)防系統(tǒng)出錯？（2）如果系統(tǒng)出錯了，如何處理以減少危害？8.5 其它測試計劃 1. 測試范圍提示：系統(tǒng)測試小組應(yīng)當根據(jù)項目的特征確定測試類型和主要內(nèi)容。一般地，系統(tǒng)測試的主要類型包括功能測試、健壯性測試、性能測試、用戶界面測試、安全性（security）測試、安裝與反安裝測試等。測試類型測試內(nèi)容、描述2. 測試方法提示：例如黑盒測試和白盒測試，解說方法。3. 測試環(huán)境與測試輔助工具測試環(huán)境測試輔助工具4. 測試完成準則提示：對于非嚴格系統(tǒng)可以采用“基于測試用例”的準則： （1）功能性測試用例通過率達到100；（2）非功能性測試用例通過率達到95時。對于嚴格系統(tǒng)，應(yīng)當補充“基于缺陷密度”的規(guī)則：（3）相鄰n個CPU小時內(nèi)“測試期缺陷密度”全部低于某個值m。例如n大于10，m小于等于1。5. 人員與任務(wù)表任務(wù)描述時間人員6. 問題與對策7. 本計劃審批意見提示：如果公司有測試經(jīng)理的話，本計劃需要測試經(jīng)理的審批。項目經(jīng)理審批意見：測試經(jīng)理審批意見：測試報告 測試報告項目名稱Java聊天室系統(tǒng)測試任務(wù)描述用戶注冊功能測試人員張三測試時間2007-8-07測試環(huán)境和工具Windows XP測試用例或測試內(nèi)容結(jié)果說明用戶名長度小于6位（1）無bug（2）發(fā)現(xiàn)bug （3）已消除bug未對用戶名做長度檢查測試總結(jié)Java編碼規(guī)范 1 介紹(Introduction) n 為什么要有編碼規(guī)范(Why Have Code Conventions)編碼規(guī)范對于程序員而言尤為重要，有以下幾個原因：- 一個軟件的生命周期中，80%的花費在于維護- 幾乎沒有任何一個軟件，在其整個生命周期中，均由最初的開發(fā)人員來維護- 編碼規(guī)范可以改善軟件的可讀性，可以讓程序員盡快而徹底地理解新的代碼- 如果你將源碼作為產(chǎn)品發(fā)布，就需要確任它是否被很好的打包并且清晰無誤，一如你已構(gòu)建的其它任何產(chǎn)品 為了執(zhí)行規(guī)范，每個軟件開發(fā)人員必須一致遵守編碼規(guī)范。每個人。n 1.2 版權(quán)聲明(Acknowledgments)本文檔反映的是Sun MicroSystems公司，Java語言規(guī)范中的編碼標準部分。主要貢獻者包括：Peter King，Patrick Naughton，Mike DeMoney，Jonni Kanerva，Kathy Walrath以及Scott Hommel。本文檔現(xiàn)由Scott Hommel維護，有關(guān)評論意見請發(fā)至2 文件名(File Names) 這部分列出了常用的文件名及其后綴。n 2.1 文件后綴(File Suffixes)Java程序使用下列文件后綴：文件類別文件后綴Java源文件.javaJava字節(jié)碼文件.classn 2.2 常用文件名(Common File Names)常用的文件名包括：文件名用途GNUmakefilemakefiles的首選文件名。我們采用gnumake來創(chuàng)建（build）軟件。README概述特定目錄下所含內(nèi)容的文件的首選文件名3 文件組織(File Organization) 一個文件由被空行分割而成的段落以及標識每個段落的可選注釋共同組成。超過2000行的程序難以閱讀，應(yīng)該盡量避免。“Java源文件范例”提供了一個布局合理的Java程序范例。n 3.1 Java源文件(Java Source Files)每個Java源文件都包含一個單一的公共類或接口。若私有類和接口與一個公共類相關(guān)聯(lián)，可以將它們和公共類放入同一個源文件。公共類必須是這個文件中的第一個類或接口。Java源文件還遵循以下規(guī)則：- 開頭注釋（參見“開頭注釋”）- 包和引入語句（參見“包和引入語句”）- 類和接口聲明（參見“類和接口聲明”） 3.1.1 開頭注釋(Beginning Comments)所有的源文件都應(yīng)該在開頭有一個C語言風格的注釋，其中列出類名、版本信息、日期和版權(quán)聲明： /* * Classname * * Version information * * Date * * Copyright notice */ 3.1.2 包和引入語句(Package and Import Statements)在多數(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)的注釋(/*/)如果有必要的話該注釋應(yīng)包含任何有關(guān)整個類或接口的信息，而這些信息又不適合作為類/接口文檔注釋。4類的(靜態(tài))變量首先是類的公共變量，隨后是保護變量，再后是包一級別的變量(沒有訪問修飾符，access modifier)，最后是私有變量。5實例變量首先是公共級別的，隨后是保護級別的，再后是包一級別的(沒有訪問修飾符)，最后是私有級別的。6構(gòu)造器7方法這些方法應(yīng)該按功能，而非作用域或訪問權(quán)限，分組。例如，一個私有的類方法可以置于兩個公有的實例方法之間。其目的是為了更便于閱讀和理解代碼。4 縮進排版(Indentation) 4個空格常被作為縮進排版的一個單位?？s進的確切解釋并未詳細指定(空格 vs. 制表符)。一個制表符等于8個空格(而非4個)。n 4.1 行長度(Line Length)盡量避免一行的長度超過80個字符，因為很多終端和工具不能很好處理之。注意：用于文檔中的例子應(yīng)該使用更短的行長，長度一般不超過70個字符。n 4.2 換行(Wrapping Lines)當一個表達式無法容納在一行內(nèi)時，可以依據(jù)如下一般規(guī)則斷開之：- 在一個逗號后面斷開- 在一個操作符前面斷開- 寧可選擇較高級別(higher-level)的斷開，而非較低級別(lower-level)的斷開- 新的一行應(yīng)該與上一行同一級別表達式的開頭處對齊- 如果以上規(guī)則導(dǎo)致你的代碼混亂或者使你的代碼都堆擠在右邊，那就代之以縮進8個空格。 以下是斷開方法調(diào)用的一些例子： someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5); var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 以下是兩個斷開算術(shù)表達式的例子。前者更好，因為斷開處位于括號表達式的外邊，這是個較高級別的斷開。 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /PREFFER longName1 = longName2 * (longName3 + 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 synchronized 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) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS /USE THIS INDENTATION INSTEAD if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); /OR USE THIS if (condition1 & condition2) | (condition3 & condition4) |!(condition5 & 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+中見過的，使用/*.*/和/界定的注釋。文檔注釋(被稱為“doc comments”)是Java獨有的，并由/*.*/界定。文檔注釋可以通過javadoc工具轉(zhuǎn)換成HTML文件。實現(xiàn)注釋用以注釋代碼或者實現(xiàn)細節(jié)。文檔注釋從實現(xiàn)自由(implementation-free)的角度描述代碼的規(guī)范。它可以被那些手頭沒有源碼的開發(fā)人員讀懂。注釋應(yīng)被用來給出代碼的總括，并提供代碼自身沒有提供的附加信息。注釋應(yīng)該僅包含與閱讀和理解程序有關(guān)的信息。例如，相應(yīng)的包如何被建立或位于哪個目錄下之類的信息不應(yīng)包括在注釋中。在注釋里，對設(shè)計決策中重要的或者不是顯而易見的地方進行說明是可以的，但應(yīng)避免提供代碼中己清晰表達出來的重復(fù)信息。多余的注釋很容易過時。通常應(yīng)避免那些代碼更新就可能過時的注釋。注意：頻繁的注釋有時反映出代碼的低質(zhì)量。當你覺得被迫要加注釋的時候，考慮一下重寫代碼使其更清晰。注釋不應(yīng)寫在用星號或其他字符畫出來的大框里。注釋不應(yīng)包括諸如制表符和回退符之類的特殊字符。n 5.1 實現(xiàn)注釋的格式(Implementation Comment Formats)程序可以有4種實現(xiàn)注釋的風格：塊(block)、單行(single-line)、尾端(trailing)和行末(end-of-line)。5.1.1 塊注釋(Block Comments)塊注釋通常用于提供對文件，方法，數(shù)據(jù)結(jié)構(gòu)和算法的描述。塊注釋被置于每個文件的開始處以及每個方法之前。它們也可以被用于其他地方，比如方法內(nèi)部。在功能和方法內(nèi)部的塊注釋應(yīng)該和它們所描述的代碼具有一樣的縮進格式。塊注釋之首應(yīng)該有一個空行，用于把塊注釋和代碼分割開來，比如： /* * 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 * two * three */ 注意：如果你不使用indent(1)，就不必在代碼中使用/*-，或為他人可能對你的代碼運行indent(1)作讓步。參見“文檔注釋”5.1.2 單行注釋(Single-Line Comments)短注釋可以顯示在一行內(nèi)，并與其后的代碼具有一樣的縮進層級。如果一個注釋不能在一行內(nèi)寫完，就該采用塊注釋(參見“塊注釋”)。單行注釋之前應(yīng)該有一個空行。以下是一個Java代碼中單行注釋的例子： if (condition) /* Handle the condition. */ . 5.1.3 尾端注釋(Trailing Comments)極短的注釋可以與它們所要描述的代碼位于同一行，但是應(yīng)該有足夠的空白來分開代碼和注釋。若有多個短注釋出現(xiàn)于大段代碼中，它們應(yīng)該具有相同的縮進。以下是一個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ù)多行的代碼段。以下是所有三種風格的例子： if (foo 1) / Do a double-flip. . else return false; / Explain why here. /if (bar 1) / / / Do a triple-flip. / . / /else / return false; / n 5.2 文檔注釋(Documentation Comments)注意：此處描述的注釋格式之范例，參見“Java源文件范例”若想了解更多，參見“How to Write Doc Comments for Javadoc”，其中包含了有關(guān)文檔注釋標記的信息(return, param, see)：/javadoc/writingdoccomments/index.html若想了解更多有關(guān)文檔注釋和javadoc的詳細資料，參見javadoc的主頁：/javadoc/index.html文檔注釋描述Java的類、接口、構(gòu)造器，方法，以及字段(field)。每個文檔注釋都會被置于注釋定界符/*.*/之中，一個注釋對應(yīng)一個類、接口或成員。該注釋應(yīng)位于聲明之前： /* * The Example class provides . */ public class Example . 注意頂層(top-level)的類和接口是不縮進的，而其成員是縮進的。描述類和接口的文檔注釋的第一行(/*)不需縮進；隨后的文檔注釋每行都縮進1格(使星號縱向?qū)R)。成員，包括構(gòu)造函數(shù)在內(nèi)，其文檔注釋的第一行縮進4格，隨后每行都縮進5格。若你想給出有關(guān)類、接口、變量或方法的信息，而這些信息又不適合寫在文檔中，則可使用實現(xiàn)塊注釋(見5.1.1)或緊跟在聲明后面的單行注釋(見5.1.2)。例如，有關(guān)一個類實現(xiàn)的細節(jié)，應(yīng)放入緊跟在類聲明后面的實現(xiàn)塊注釋中，而不是放在文檔注釋中。文檔注釋不能放在一個方法或構(gòu)造器的定義塊中，因為Java會將位于文檔注釋之后的第一個聲明與其相關(guān)聯(lián)。6 聲明(Declarations) n 6.1 每行聲明變量的數(shù)量(Number Per Line)推薦一行一個聲明，因為這樣以利于寫注釋。亦即， int level; / indentation level 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 n 6.2 初始化(Initialization)盡量在聲明局部變量的同時初始化。唯一不這么做的理由是變量的初始值依賴于某些先前發(fā)生的計算。n 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 maxLoops; i+) . 避免聲明的局部變量覆蓋上一級聲明的變量。例如，不要在內(nèi)部代碼塊中聲明相同的變量名： int count; . myMethod() if (condition) int count = 0; / AVOID! . . n 6.4 類和接口的聲明(Class and Interface Declarations)當編寫類和接口是，應(yīng)該遵守以下格式規(guī)則：- 在方法名與其參數(shù)列表之前的左括號“(”間不要有空格- 左大括號“”位于聲明語句同行的末尾- 右大括號“”另起一行，與相應(yīng)的聲明語句對齊，除非是一個空語句，“”應(yīng)緊跟在“”之后 class Sample extends Object int ivar1; int ivar2; Sample(int i, int j) ivar1 = i; ivar2 = j; int emptyMethod() . - 方法與方法之間以空行分隔 7 語句(Statements) n 7.1 簡單語句(Simple Statements)每行至多包含一條語句，例如： argv+; / Correct argc-; / Co