javadoc注释規範

原创

ATIP团 2012-12-21 10:54:20 博主文章分类：java技術 ©著作权

文章标签 模板 Eclipse javadoc 快捷鍵 文章分类 Java 后端开发

©著作权归作者所有：来自51CTO博客作者ATIP团的原创作品，请联系作者获取转载授权，否则将追究法律责任

（一）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标签来进行排版、突出重点等。如 会使javadoc文档换行；a在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倒序排列 
* 参数要求：blProgram中pkCode 不为空 
* 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) {……}