javadoc註釋規範

（一）javadoc註釋

（1）建議爲代碼編寫完備的javadoc註釋。

這類註釋可以由IDE自動進行提示，從而爲代碼編寫提供極大的便利。Eclipse中對javadoc註釋的相關配置參見後文。

下述javadoc註釋模板中，“@author”等是javadoc可以識別的標籤，生成javadoc文檔時其內容會寫入文檔中。Javadoc可識別的標籤主要包括：@see：引用其他類；@version：版本號；@author：作者；@since：版本支持；@param：參數；@return：返回值；@throws：拋出異常；@deprecated：過期；{@link }及{@linkplain }：創建指向其它javadoc的鏈接。不可識別的標籤即使會在Eclipse的javadoc提示功能中顯示出來，在生成html格式的api文檔時也會報錯，並且不會寫入文檔中。

“（個人簽名）”、“（類描述）”等需要在配置或寫javadoc時按上下文替換掉。如團長的“（個人簽名）”被配置成了“Severus Lynn”。

“TODO”會在Eclipse中生成一個“未完成工作標記”。Eclipse會以“”圖標指出這一行中有此標記，提示用戶去完成相應工作。

“${date}”、${time}等會由Eclipse在增加javadoc註釋時自動替換爲實際的值。在方法的javadoc中，${tags}標記會自動替換爲方法的@param、@return和可能的@throws。

Javadoc中可以使用html標籤來進行排版、突出重點等。如<br />會使javadoc文檔換行；<strong>a</strong>在javadoc文檔中會顯示爲“a”。

上述字符如果要作爲javadoc的一部分，在註釋中直接展示出來的話，可以使用{@code }標籤。

（2）建議爲類文件編寫如下javadoc註釋：

/**
* @author: （個人簽名）
* @date: ${date}-${time}
*/

例如：

/**
* @author: Severus Lynn
* @date: 2012-4-16-下午4:28:03
*/

（3）建議爲類編寫如下javadoc註釋：

/**
* TODO: （類描述）
*
* @author （個人簽名）
* @since ${date}
* ${tags}
*/

例如：

/**
* 用於測試的dao
*
* @author Severus Lynn
* @since 2012-4-16
*/
public final class TestDao {……}

（4）建議爲字段編寫如下javadoc註釋：

/**
* TODO:（字段描述）
*
* @author （個人簽名）
* @since ${date}
*/

例如：

/**
* 數據庫鏈接
* @author Severus Lynn
* @since 2012-4-16
*/
private static Connection connection;

（5）建議爲構造方法編寫如下javadoc註釋：

/**
* TODO:（構造方法描述）
*
* @author （個人簽名）
* @since ${date}
* ${tags}
*/

例如：

/**
* 構造方法，主要初始化數據庫鏈接
*
* @author Severus Lynn
* @since 2012-4-19
* @throws SQLException
*                         執行connection.isClosed()時可能拋出該異常
*/
public TestDao() throws SQLException {……}

（6）建議爲普通方法編寫如下javadoc註釋：

/**
* TODO:（方法描述）
*
* @author （個人簽名）
* @since ${date}
* ${tags}
*/

例如：

/**
* 查詢一行。所查詢到的結果都按“列名”-“值”映射爲Map<String,String>
*
* @author Severus Lynn
* @since 2012-4-19
* @param sql
*                        待執行的sql查詢語句
* @return Map<String,String> 從數據庫中檢索得到的結果
*/
public Map<String, String> selectSingleRow(String sql) {……}

（7）建議爲覆蓋（接口或父類的）方法編寫如下javadoc註釋：

/**
* TODO:（方法描述）
*
* @author （個人簽名）
* @since ${date}
* ${tags}
* ${see_to_overridden}
*
*/

例如：

/**
* 根據pkCode從t_atip_tasktabllog表中查出複覈記錄。記錄按serialNo倒序排列<br />
* 參數要求：blProgram中pkCode 不爲空<br />
* 2012-04-16的實現中，沒有使用頁碼參數
*
* @author Severus Lyyn
* @since 2012-4-19
* @see com.sinosig.atip.tasktable.service.ITaskTableLogService#queryCheckListLogByProNo(com.sinosig.atip.tasktable.model.BLTaskTableLog,
*            int, int)
*/
@Override
public List<BLTaskTableLog> queryCheckListLogByProNo(……}

（8）建議爲委託方法編寫如下javadoc註釋：

/**
* ${tags}
* ${see_to_target}
*/

（9）建議爲getter方法編寫如下javadoc註釋：

/**
* @return the {@link #${bare_field_name} }
*/

例如：

/**
* @return the {@link #auditMainHaveSon }
*/
public String getCheckStatus() {……}

（10）建議爲setter方法編寫如下javadoc註釋：

/**
* @param ${param} the {@link #${bare_field_name} }to set
*/

例如：

/**
* @param auditMainHaveSon
*                        the {@link #auditMainHaveSon }to set
*/
public void setCheckStatus(String checkStatus) {……}

（二）Eclipse中對javadoc註釋的相關配置

（1）註釋模板配置

Eclipse中javadoc註釋模板配置位於：windows→preferences→java→code style→code templates，展開右側窗口中的“comments”選項，對各子項目模板進行配置，如下圖所示。

圖-1.  Eclipse中javadoc註釋模板配置

（2）javadoc註釋的快捷鍵配置

Eclipse增加javadoc註釋的快捷鍵配置位於：windows→preferences→keys，在右側查找“Add Javadoc Comment”，選中後在下部“Bindding”輸入框內綁定快捷鍵。如下圖綁定的快捷鍵是“Alt + W”。

圖-2.  Eclipse增加javadoc註釋的快捷鍵配置

（3）查看javadoc的方式

Eclipse中查看javadoc的方式有兩種。

1、鼠標懸停在某個元素（類名，方法名，變量名）上，在默認配置下，如果元素有對應的javadoc，Eclipse將以懸浮框的形式進行提示。

2、通過windows→show view打開javadoc視圖。對鼠標選定的元素，如果元素有對應的javadoc，Eclipse將在javadoc視圖中進行提示。