（一）javadoc注释

（1） 建议 为代码编写完备的javadoc注释。
这类注释可以由IDE自动进行提示，从而为代码编写提供极大的便利。Eclipse中对javadoc注释的相关配置参见 後文。

下述javadoc注释模板中，“@author”等是javadoc可以识别的标签，生成javadoc文档时其内容会写入文档中。Javadoc可识别的标签主要包括： @see：引用其他类 ； @version：版本号 ； @author：作者 ； @since：版本支持 ； @param：参数 ； @return：返回值 ； @throws：抛出异常 ； @deprecated：过期 ；{@link } 及 {@link plain  }：创建指向其它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视图中进行提示。