你該知道的Java註釋！

本文首發於我的微信公衆號《andyqian》,期待你的關注！

前言

  有好幾天沒有寫文章了，實在抱歉。今天咱們來講說如何編寫Java註釋。使用過Java的同窗都很是熟悉，Java中有:

• 單行註釋 // 這是單註釋

• 多行註釋 /*這是多行註釋*/  

• Javadoc註釋 /**這是javadoc註釋*/  

其實這裏面還有不少細節呢，下面咱們一一來揭曉

哪些地方須要添加註釋

  首先，咱們須要肯定一下，添加註釋的目的是什麼？(手動思考10秒)。

我認爲添加註釋，是爲了程序更容易理解與維護，特別是維護，更是對本身代碼負責的一種體現。

那基於這樣的目的，在平常開發中，咱們須要在哪些地方添加註釋呢？

• 類，接口。

這一部分註釋是必須的。在這裏，咱們須要使用javadoc註釋，須要標明，建立者，建立時間，版本，以及該類的做用。以下所示:

package com.andyqian.utils;

/**
 * @author: andy
 * @date: 18-01-05
 * @version: 1.0.0
 * @description: 生成PDF 工具類
 */
public class PdfUtil {

}

• 方法

在方法中，咱們須要對入參，出參，以及返回值，均要標明。以下所示：

   /**
     * 生成pdf文件
     * @param htmlContent  待生成pdf的 html內容
     * @param file  生成pdf文件地址
     * @see  PdfUtils#getFontPath()
     * @return true 生成成功    false 生成失敗
     */
    public static boolean generatePdf(String htmlContent,File file){
        ...
        return result;
    }

• 常量

對常量，咱們須要使用多行註釋，進行標明該常量的用途，以下所示:

/**
 * @author: andy
 * @date: 18-01-05
 * @version: 0.0.1
 * @description:
 */
public class StatusConsts {

    /**
     * 博客地址
     */
    public static final String BLOG="www.andyqian.com";
}

• 關鍵算法上

在關鍵算法上，添加註釋而且按照順序依次標明，寫明白該方法爲何這麼作。以下所示:

/**
     * 應用場景:
     * 1.在windows下,使用Thread.currentThread()獲取路徑時,出現空對象，致使不能使用
     * 2.在linux下,使用PdfUtils.class獲取路徑爲null,
     * 獲取字體路徑
     * @return 返回字體路徑
     */
    private static String getFontPath(){
        String path="";
        // 1.
        ClassLoader classLoader= Thread.currentThread().getContextClassLoader();
        URL url = (classLoader==null)?null:classLoader.getResource("/");
        String threadCurrentPath = (url==null)?"":url.getPath();
        // 2. 若是線程獲取爲null,則使用當前PdfUtils.class加載路徑
        if(threadCurrentPath==null||"".equals(threadCurrentPath)){
            path = PdfUtils.class.getClass().getResource("/").getPath();
        }
        // 3.拼接字體路徑
        StringBuffer stringBuffer = new StringBuffer(path);
        stringBuffer.append("/fonts/SIMKAI.TTF");
        path = stringBuffer.toString();
        return path;
    }

怎麼添加註釋?

1. IDEA 自動生成
  對於類中的註釋，咱們能夠經過IDEA自動生成。
如IDEA 能夠經過：File->Settings->Editor->File and Code Templates->Includes->File Header來設置模板，這樣新建文件時，IDEA會按照設置的模板，會自動生成一個註釋，就不須要一個一個敲了。

其中標籤有:
${USER} : 當前用戶。
${DATE} : 當前日期。
${PACKAGE_NAME}：包名。
${TIME}: 當前時間。
${YEAR}： 當前年。
${MONTH}：當前月。
${DAY}: 當前日。
${HOURS}： 當前小時。
${MINUTE}: 當前分鐘

1. 註釋引用

若是方法中引用了其餘的方法，在註釋中如何體現呢？細心的朋友，應該已經發現了，在上面的：

   /**
     * 生成pdf文件
     * @param htmlContent  待生成pdf的 html內容
     * @param file  生成pdf文件地址
     * @see  PdfUtils#getFontPath()
     * @return true 生成成功    false 生成失敗
     */
    public static boolean generatePdf(String htmlContent,File file){
        ...
        return result;
    }

中的@see就有這個做用，其語法是:

@see package.class#method  label
@see  #field
@see  #method(Type, Type,...)
@see  #method(Type argname, Type argname,...)
@see  #constructor(Type, Type,...)
@see  #constructor(Type argname, Type argname,...)

例如:

@see  PdfUtils#getFontPath()

若是是同一個類中，package(包名全路徑)能夠省略。有相同功能的標籤有:
{@link package.class#metod}

   /**
     * 生成pdf文件
     * @return true 生成成功    false 生成失敗
     * @throws  Exception
     * {@link PdfUtils#getFontPath()}
     */
    public static boolean generatePdf(String htmlContent,File file){
        ....
    }

其區別是：@see必需要在註釋行首，{@link}能夠在任意位置。

1. 在IDEA中，咱們能夠選中方法經過快捷鍵Ctrl+D便可查看咱們添加的註釋，以下圖所示:

2. 若是須要引用外網的鏈接，咱們能夠經過HTML標籤中的a標籤來表示，以下所示:

   @see <a href="http://www.andyqian.com">博客地址</a>

如下爲javadoc 須要熟知的註釋標籤:
@see 引用類/方法。
@author: 做者。
@date：日期。
@version: 版本號。
@throws：異常信息。
@param：參數
@return： 方法返回值。
@since: 開源項目經常使用此標籤用於建立日期 。
{@value}: 會使用該值，經常使用於常量。
{@link} 引用類/方法。
{@linkplain} 與@link功能一致。

完整案例以下:

package com.andyqian.pdf.utils;

import com.itextpdf.text.log.Logger;
import com.itextpdf.text.log.LoggerFactory;

import java.io.File;
import java.net.URL;

/**
 * @author: 鞠騫
 * @date: 18-01-05
 * @version: 1.0.0
 * @description: 生成PDF 工具類
 */
public class PdfUtils {
    private static final Logger logger = LoggerFactory.getLogger(PdfUtils.class);

    /**
     * 生成pdf文件
     * @param htmlContent  待生成pdf的 html內容
     * @param file  生成pdf文件地址
     * @see  <a href="https://itextpdf.com/">https://itextpdf.com/</a>
     * @return true 生成成功    false 生成失敗
     */
    public static boolean generatePdf(String htmlContent,File file)throws Exception{
        ...
        return true;
    }

    /**
     * 應用場景:
     * 1.在windows下,使用Thread.currentThread()獲取路徑時,出現空對象，致使不能使用
     * 2.在linux下,使用PdfUtils.class獲取路徑爲null,
     * 獲取字體路徑
     * @return 返回字體路徑
     */
    private static String getFontPath(){
        String path="";
        // 1.
        ClassLoader classLoader= Thread.currentThread().getContextClassLoader();
        URL url = (classLoader==null)?null:classLoader.getResource("/");
        String threadCurrentPath = (url==null)?"":url.getPath();
        // 2. 若是線程獲取爲null,則使用當前PdfUtils.class加載路徑
        if(threadCurrentPath==null||"".equals(threadCurrentPath)){
            path = PdfUtils.class.getClass().getResource("/").getPath();
        }
        // 3.拼接字體路徑
        StringBuffer stringBuffer = new StringBuffer(path);
        stringBuffer.append("/fonts/SIMKAI.TTF");
        path = stringBuffer.toString();
        return path;
    }
}

添加註釋時的一點建議

1. 類中，接口等必須有建立時間，建立人，版本號，描述等註釋。

2. 註釋不是越多越好，好比：get/set方法就不須要寫註釋。更不須要每一行都寫註釋。

3. 註釋須要寫的簡明易懂。特別是方法的參數，以及返回值。

4. 每一次修改時，相應的註釋也應進行同步更新。

5. 在類，接口，方法中，應該都使用/** */javadoc註釋。由於這樣調用者就不須要進入方法內部才知道方法的用處。提升編碼效率。

6. 方法代碼中若是有順序之分，最好將代碼也加上序號，如1，2，3等。

7. 枚舉中的每個值都須要添加註釋。

小結

  寫註釋是一個好習慣，能讓本身和團隊都受益，若是你接手一個一丁點註釋都沒有的項目，那麼上一個程序員就倒黴了(此處省略N個字)，不知大家有沒有看過開源項目的源碼，那註釋寫的至關詳細，你們能夠多多參考，爭取別作一個」倒黴」的程序員。

相關閱讀
談談MySQL存儲引擎

淺談MySQL表結構設計

談談MySQL顯示類型轉換

Java PDF生成方案之iText

 

掃碼關注，一塊兒進步

我的博客: http://www.andyqian.com