Java 註釋規範

我是清都山水郎，天教懶慢帶疏狂。曾批給露支風券，累奏流雲借月章。
詩萬首，酒千觴，幾曾着眼看侯王。玉樓金闕慵歸去，且插梅花醉洛陽。

一、概覽

好的註釋每每能減小提供協同開發的工做效率，以及極大的提高系統的可維護性。所以寫好代碼註釋也是一個很重要的事情。
Javadoc 通常分爲三段：

• 第一段：概要描述
  一般用一句話描述類或方法的做用，且以 . 結尾
• 第二段：詳細描述
• 第三段：文檔標註，用於標註做者、建立時間、參閱類等信息。

效果圖

二、註釋介紹

如下只介紹經常使用的註釋

標籤	描述	做用域
@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;

    /**
     * 獲取訂單號.
     *
     * 訂單號生成格式以下
     * <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);
}

四、生成 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 文件

既然選擇了遠方，即便天寒地凍，路遙馬亡，我本就一無全部，又有何懼。