5.4 KiB

Raw Permalink Blame History

Java文档注释规范倡议

什么是文档注释

以/**开头的就是文档注释，它只可出现在类头，方法头，类成员头上。这种注释会被maven打包后保留，且受JavaDoc与IDE识别。可以进行更为格式化的表现。

为什么要写好文档注释，文档注释有什么优势

1、文档注释受IDE识别，能提高编写代码的速度

我们使用IDEA编写代码时，调用到一个写了文档注释的方法。我们可以通过Ctrl+Q打开对应的文档注释。从而避免在调用方法时，需要打开该方法的代码页，导致两页代码翻来翻去导致思路打乱的情况。如图：

2、JavaDoc可以识别文档注释生成Java类文档

3、接口API文档框架JApiDocs可以识别

JApiDocs是一个基于文档注释生成API文档框架。它比起Swagger，可以避免单行内太多注解，或注解内容太长而导致代码臃肿难看的情况。

如何写好基本的文档注释

在写好方法声明后，在方法头输入“/**”后按回车，即可自动生成对应的文档模版，输入对应的内容即可。
正例：反例：反例不可被JavaDoc识别

文档注释基本格式以及常用注解详解

一、基本格式

/**
 * 12315初查反馈延期
 * @param targetUser 回填用户 {@link AICUser}
 * @param caseguid 工单caseguid
 * @param regId 工单号
 * @param formType 表单类型
 * @param prevDate  延期前日期 {@link java.util.Date}
 * @param delayDate 延期日期（延期至该日期）{@link java.util.Date}
 * @return 回填结果
 * @author lroyia
 * @since 2020年11月20日 14:07:48
 */
FeedbackResultDto acceptDelay(AICUser targetUser, String regId, String caseguid, String formType, Date prevDate, Date delayDate);

一般文档注释以下面的顺序进行编写

1、方法描述

方法描述必须写在所有注解文档描述的前面，不然不会被识别

2、参数说明

使用@param进行参数描述
使用格式：

@param 参数名 参数描述

3、返回说明

使用@return 进行返回内容标识
使用格式：

@return 返回描述

4、异常抛出说明

使用@throws或@exception进行异常说明
@throws与@exception注解均为异常注释注解，两者是同义词，作用一致
使用格式：

@throws 方法抛出的异常类名 异常描述
@exception 方法抛出的异常类名 异常描述

5、作者说明

使用@author进行作者标识
使用格式：

@author 作者名称

6、编写时间

使用@since进行编写时间标识，@since常用于标识方法从哪个版本开始编写，因为公司没有严格，细粒度的项目版本控制，所以暂时使用该注解进行时间描述
使用格式：

@since 时间描述

二、常用注解详解

1、@code

@code是用于文档中的代码格式化转义，相当于在文档中使用<code>标签
使用格式：

{@code 修饰内容}

2、@link

@link是用于进行档内文件超链接，常用语修饰一些方法对项目中相关的文件的连接。例如，方法使用了某个枚举，我们就可以在文档中使用@link生成对应枚举类的超链接，这样阅读者就可以直接点击文档中的超链接跳到对应的枚举类中。
使用格式：

{@link 类名#方法名(参数名)}

3、@see

@see是类文档引用注解，它与@link相似。但两者行为和注解位置不同。@code和@link均为行内注解均在{}花括号中使用，可在任何描述位置进行扩展修饰。@see是行注解，需要像@param一样占单行。@link默认行为是打开目标类指定位置，@see默认行为是展示目标的文档注释。
使用格式：

@see 类名#方法名(参数名)

4、@param

@param是专门对方法的参数进行描述的注解，被标识的参数信息会固定出现在文档的参数部位。
使用格式：

@param 参数名 参数描述

5、@return

@return是专门对方法的返回内容进行描述的注解，被标识的信息会固定出现在文档的返回部位。
使用格式：

@return 返回描述

6、@throws和@exception

@throws与@exception注解均为异常注释注解，两者是同义词，作用一致。在使用异常注释注解前，必须确保方法已使用throws关键字进行了相应的异常抛出声明。
使用格式：

@throws 方法抛出的异常类名 异常描述
@exception 方法抛出的异常类名 异常描述

7、@author

@author注解是专门用于标识方法作者的一个注解
使用格式：

@author 作者名称

8、@since

@since是专门用于标识方法/类的创建版本时间的一个注解。在没有明确的版本划分时，我们可以用来进行标识创建时间。
使用格式：

@since 创建时间/版本描述

9、@version

@version是专门用来标识当前方法/类的版本的注解，常在开发社区的开源项目中使用，一般公司不会进行。
使用格式：

@version 版本号

5.4 KiB Raw Permalink Blame History Unescape Escape