java的注释规范_Java 注释规范

我是清都山水郎，天教懒慢带疏狂。曾批给露支风券，累奏流云借月章。

诗万首，酒千觞，几曾着眼看侯王。玉楼金阙慵归去，且插梅花醉洛阳。

一、概览

好的注释每每能减小提供协同开发的工做效率，以及极大的提高系统的可维护性。所以写好代码注释也是一个很重要的事情。

Javadoc 通常分为三段：html

第一段：概要描述

一般用一句话描述类或方法的做用，且以 . 结尾

第二段：详细描述

第三段：文档标注，用于标注做者、建立时间、参阅类等信息。

效果图

java

二、注释介绍

如下只介绍经常使用的注释apache

标签

描述

做用域

@author

标注类的做者

类

@deprecated

标注类或者方法过期

类、方法

@exception

标注方法抛出的异常

方法

@throws

与 @exception 一致

方法

{@inheritDoc}

从直接父类继承的注释

类、方法

{@link}

插入一个到另一个主题的连接

类、方法

@param

说明方法参数

方法

@return

说明方法返回值

方法

@see

指定一个到另外一个主题的连接

类、方法

@since

标记从何时引入的

类、方法

@version

指定类的版本

类

{@value}

显示常量的值

须要被 final 修饰

三、demo

/**

* 订单服务类

*

* @author 陈少平

* @version 1.0

*/

public interface OrderService {

/**

* 订单状态,表示关闭 {@value}

*

* @see OrderType

*/

int STATUS_CLOSE = 1;

/**

* 获取订单号.

*

* 订单号生成格式以下

*

{@code

* String sn = orderId + RandomUtil.randomLong()

* }

*

* @param orderId 订单id

* @param orderType {@link OrderType}

* @exception IOException 读取订单失败

* @throws NullPointerException 若是 {@code orderId} null.

* @return {@literal }

*

* @since 1.2

* @see OrderType#success

*/

Map getOrderSn(Long orderId, int orderType) throws IOException;

/**

* @deprecated 获取订单状态.

*

* @param orderId 订单id

* @return 订单状态

*

* @since 1.0

* @see OrderType#success

* @see OrderType#cancle

*/

int getStatus(Long orderId);

}

四、生成 Javadoc

maven 中引入 javadoc 插件

org.apache.maven.plugins

maven-javadoc-plugin

utf-8

utf-8

true

none

attach-javadocs

jar

执行 mvn javadoc:javadoc

执行完命令后，会在 target/site/apidocs 目录下生成 html 文件api

既然选择了远方，即便天寒地冻，路遥马亡，我本就一无全部，又有何惧。