汽车后市场新说
新浪微博
微信
当前位置:汽车后市场新说网 » 周刊

你该知道的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会按照设置的模板,会自动生成一个注释,就不需要一个一个敲了。

你该知道的Java注释!

其中标签有:

${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即可查看我们添加的注释,如下图所示:
你该知道的Java注释!


  1. 如果需要引用外网的连接,我们可以通过HTML标签中的a标签来表示,如下所示:
@see 博客地址

以下为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 https://itextpdf.com/
* @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个字),不知你们有没有看过开源项目的源码,那注释写的相当详细,大家可以多多参考,争取别做一个”倒霉”的程序员。

你该知道的Java注释!