你该知道的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