java 註釋規範

阿新 • • 發佈：2020-12-11

技術標籤：java java

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

文章目錄

1、概覽

好的註釋往往能減少提供協同開發的工作效率，以及極大的提升系統的可維護性。因此寫好程式碼註釋也是一個很重要的事情。
Javadoc 一般分為三段：

第一段：概要描述
通常用一句話描述類或方法的作用，且以 . 結尾
第二段：詳細描述
第三段：文件標註，用於標註作者、建立時間、參閱類等資訊。

效果圖
[外鏈圖片轉存失敗,源站可能有防盜鏈機制,建議將圖片儲存下來直接上傳(img-taDGKoz8-1607605740478)(evernotecid://B58292A4-43F3-4C3E-ACA3-E9C7D829CC18/appyinxiangcom/15559189/ENResource/p3093)]

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

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>