第4章
大B：“嗬嗬嗬！寫得不錯，不虧是C大的高材生。”
小A：“師兄你這不是在取笑我嘛！我還有好多問題得請教你哩！”
大B：“行行行……沒問題。小師弟好學，師兄哪能袖手旁觀呐！對了，你寫代碼的時候一定要注意代碼的規範。”
小A：“代碼規範？”
大B：“嗯，來來來，我說給你聽。首先是要注意注釋文檔的格式，注釋文檔將用來生成HTML格式的代碼報告，所以注釋文檔必須書寫在類、域、構造函數、方法、定義之前。注釋文檔由兩部分組成——描述、塊標記。”
例如：
注釋
@author大。
@version1.10
publicvoiddoGet（HttpServletRequestrequest，HttpServletResponseresponse）
throwsServletException，IOException{
doPost（request，response）；
}
大B：“看！前兩行為描述，描述完畢後，由@符號起頭為塊標記。”
大B：“然後是注釋的種類。有文件頭注釋、構造函數注釋、域注釋、方法注釋和定義注釋。”
小A：“什麽？注釋還有那麽多的種類的？我以前都沒有用心去記過它的喔。師兄能不能給我講講每一種注釋的功能和要求啊？”
大B：“這有什麽問題哩！舉些例子來講，那樣你就容易理解多了。”
小A：“嘿嘿！那感情好。”
大B：“文件頭注釋已結束，需要注明該文件創建時間，文件名，命名空間信息。”
例如：
描述部分用來書寫該類的作用或者相關信息，塊標記部分必須注明作者和版本。
如：
classWindowextendsBaseWindow{
……
}
大B：“構造函數注釋采用描述部分注明構造函數的作用，不一定有塊標記部分。域注釋可以出現在注釋文檔裏麵，也可以不出現在注釋文檔裏麵。用的域注釋將會被認為是注釋文檔出現在最終生成的HTML報告裏麵，而使用的注釋會被忽略。這個應該注意！”
例如：
booleanisTrigerSuccess=false；
又例如：
booleanisTrigerSuccess=false；
再例如：
intx=1263732；
大B：“還有就是方法注釋，方法注釋采用描述部分注明方法的功能，塊標記部分注明方法的參數，返回值，異常等信息。定義注釋，規則同域注釋。”
小A：“喔……原注釋還真的是有那麽多種類，每個種類都有不同的功能哩！嘿嘿！看來以後我得更認真學習才行哩！”
大B：“嗬嗬……你能這麽想就好嘍！對了，小A，注釋塊標記你知道不？”
小A：“注釋塊標？嘿嘿！這個……也不知道……”
大B：“沒關係，我告訴你。首先是標記的順序。”
塊標記將采用如下順序：
……
*
*@param（classes，interfaces，methodsandconstructorsonly）
*@return（methodsonly）
*@exception（@throwsisasynonymaddedinJavadoc1.2）
*@author（classesandinterfacesonly，required）
*@version（classesandinterfacesonly，required.Seefootnote1）
*@see
*@since
*@serial（or@serialFieldor@serialData）
*@deprecated（seeHowandWhenToDeprecateAPIs）
*……
一個塊標記可以根據需要重複出現多次，多次出現的標記按照如下順序：
@author按照時間先後順序（chronological）
@param按照參數定義順序（declaration）
@throws按照異常名字的字母順序（alphabetically）
@see按照如下順序：
@see#field
@see#Constructor（Type，Type……）
@see#Constructor（Typeid，Typeid……）
@see#method（Type，Type……）
@see#method（Typeid，Type，id……）
@seeClass
@seeClass#field
@seeClass#Constructor（Type，Type……）
@seeClass#Constructor（Typeid，Typeid）
@seeClass#method（Type，Type……）
@seeClass#method（Typeid，Typeid……）
@seepackage.Class
@seepackage.Class#field
@seepackage.Class#Constructor（Type，Type……）
@seepackage.Class#Constructor（Typeid，Typeid）
@seepackage.Class#method（Type，Type……）
@seepackage.Class#method（Typeid，Type，id）
@seepackage
小A：“哇噻！塊標記還可以按照時間先後順序，按照參數定義順序，按照異常名字的字母順序哩！師兄，你講得真詳細。看來我得好好得花點心思把它們都記下來才好哩！”
大B：“能記住當然好哩！我再給你講下標記介紹。”
@param標記
@param後麵空格後跟著參數的變量名字（不是類型），空格後跟著對該參數的描述。
在描述中第一個名字為該變量的數據類型，表示數據類型的名字前麵可以有一個冠詞如：a，an，the。如果是int類型的參數則不需要注明數據類型。例如：
……
*@paramchthechar用用來……
*@paramimagetheimage用來……
*@paramnum一個數字……
……
大B：“對於參數的描述如果隻是一短語，最好不要首字母大寫，結尾也不要句號。對於參數的描述是一個句子，最好不要首字母大寫，如果出現了句號這說明你的描述不止一句話。如果非要首字母大寫的話，必須用句號來結束句子。（英文的句號）”
公司內部添加ByRef和ByVal兩個標記，例如：
*@paramimagetheimageByRef用來……
說明該參數是引用傳遞（指針），ByVal可以省略，表示是值傳遞。
大B：“代碼規範大概要點就是這些了。聽起來好像很多，隻要用心，其實也很容易記的。”
小A：“嘿嘿！師兄，你太厲害了！”