Java 注释规范

我是清都山水郎，天教懒慢带疏狂。曾批给露支风券，累奏流云借月章。
诗万首，酒千觞，几曾着眼看侯王。玉楼金阙慵归去，且插梅花醉洛阳。

1、概览

好的注释往往能减少提供协同开发的工作效率，以及极大的提升系统的可维护性。因此写好代码注释也是一个很重要的事情。
Javadoc 一般分为三段：

• 第一段：概要描述
  通常用一句话描述类或方法的作用，且以 . 结尾
• 第二段：详细描述
• 第三段：文档标注，用于标注作者、创建时间、参阅类等信息。

效果图

2、注释介绍

以下只介绍常用的注释

标签	描述	作用域
@author	标注类的作者	类
@deprecated	标注类或者方法过时	类、方法
@exception	标注方法抛出的异常	方法
@throws	与 @exception 一致	方法
{@inheritDoc}	从直接父类继承的注释	类、方法
{@link}	插入一个到另外一个主题的链接	类、方法
@param	说明方法参数	方法
@return	说明方法返回值	方法
@see	指定一个到另一个主题的链接	类、方法
@since	标记从什么时候引入的	类、方法
@version	指定类的版本	类
{@value}	显示常量的值	需要被 final 修饰

3、demo

/**
 * 订单服务类
 *
 * @author 陈少平
 * @version 1.0
 */
public interface OrderService {

    /**
     * 订单状态,表示关闭 {@value}
     *
     * @see OrderType
     */
    int STATUS_CLOSE = 1;

    /**
     * 获取订单号.
     *
     * 订单号生成格式如下
     * <pre>{@code
     * String sn = orderId + RandomUtil.randomLong()
     * }</pre>
     *
     * @param orderId 订单id
     * @param orderType {@link OrderType}
     * @exception  IOException 读取订单失败
     * @throws NullPointerException 如果 {@code orderId} null.
     * @return {@literal <订单ID,订单号>}
     *
     * @since 1.2
     * @see OrderType#success
     */
    Map<Long, String> 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);
}

4、生成 Javadoc

1. maven 中引入 javadoc 插件

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <configuration>
                <charset>utf-8</charset>
                <encoding>utf-8</encoding>
                <quiet>true</quiet>
                <doclint>none</doclint>
            </configuration>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

1. 执行 mvn javadoc:javadoc

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

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