Java是一种可以撰写跨平台应用软件的面向对象的程序设计语言。Java 技术具有卓越的通用性、高效性、平台移植性和安全性，广泛应用于PC、数据中心、游戏控制台、科学超级计算机、移动电话和互联网，同时拥有全球最大的开发者专业社群。
给你学习路线：html-css-js-jq-javase-数据库-jsp-servlet-Struts2-hibernate-mybatis-spring4-springmvc-ssh-ssm
前言
今天我们来说说如何编写Java注释。使用过Java的同学都非常熟悉，Java中有:
单行注释 // 这是单注释
多行注释 /*这是多行注释*/
Javadoc注释 /**这是javadoc注释*/
其实这里面还有很多细节呢，下面我们一一来揭晓
小编推荐一个学Java的学习裙【 六五零，五五四，六零七 】，无论你是大牛还是小白，是想转行还是想入行都可以来了解一起进步一起学习！裙内有开发工具，很多干货和技术资料分享！
在这里相信有许多想要学习Java的同学，大家可以关注我哦
哪些地方需要添加注释
首先，我们需要确定一下，添加注释的目的是什么？(手动思考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}: 当前分钟
注释引用
如果方法中引用了其他的方法，在注释中如何体现呢？细心的朋友，应该已经发现了，在上面的：
/** * 生成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}可以在任意位置。
在IDEA中，我们可以选中方法通过快捷键Ctrl+D即可查看我们添加的注释，如下图所示:
小编推荐一个学Java的学习裙【 六五零，五五四，六零七 】，无论你是大牛还是小白，是想转行还是想入行都可以来了解一起进步一起学习！裙内有开发工具，很多干货和技术资料分享！
如果需要引用外网的连接，我们可以通过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 * @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; }}
添加注释时的一点建议
类中，接口等必须有创建时间，创建人，版本号，描述等注释。
注释不是越多越好，比如：get/set方法就不需要写注释。更不需要每一行都写注释。
注释需要写的简明易懂。特别是方法的参数，以及返回值。
每一次修改时，相应的注释也应进行同步更新。
在类，接口，方法中，应该都使用/** */javadoc注释。因为这样调用者就不需要进入方法内部才知道方法的用处。提高编码效率。
方法代码中如果有顺序之分，最好将代码也加上序号，如1，2，3等。
枚举中的每一个值都需要添加注释。
小编推荐一个学Java的学习裙【 六五零，五五四，六零七 】，无论你是大牛还是小白，是想转行还是想入行都可以来了解一起进步一起学习！裙内有开发工具，很多干货和技术资料分享！
小结
写注释是一个好习惯，能让自己和团队都受益，如果你接手一个一丁点注释都没有的项目，那么上一个程序员就倒霉了(此处省略N个字)，不知你们有没有看过开源项目的源码，那注释写的相当详细，大家可以多多参考，争取别做一个”倒霉”的程序员。
下面是小编整理的一整套系统的Java学习教程，大家可以关注小编哦
