Java 中的注释详解

不管是那种编程语言， 代码的注释都是必备的语法功能， 并且一个好的程序的指标之一，就是能有一个好的注释。 那 Java 中的注释是怎么定义的呢？ 我们来说说。

Java 中 3 种注释类型

• 单行注释
• 多行注释
• 文档注释

单行注释

单行注释： Java 中最简单的注释方法， 使用两个反斜杠 // 就可以了。注释的内容从 // 开始。

举个例子：

单行注释不仅可以注释备注信息， 并且也可以注释代码内容。

  // 返回一个字符串
  //return "苗子说全栈 ";
  return "";

在学习初期可以使用 System.out 输出字符串进行一些调试， 初学可以考虑这个， 后期学习日志框架之后， 推荐使用日志的方式输出调试信息。这里只是演示单行注释的用法。

单行注释的推荐写法就是写在代码的上一行中。

多行注释

多行注释：Java 中使用以 /* 开始， 以 */ 结束的注释方式。

举个例子：

需要注意：

对于多行注释开始和结束中间不要再有结束符。为了好看会在注释内容首字母写入 * 举例说明：

//正确的
/*
 * 多行注释
 */

//错误的实例
/*
 *这个是多行注释
/*
 *多行注释内容
 */
*/  这里就错误了。 

匹配规则就是 /* 与之对应的最近的 */ 结束符。

除了单行注释和多行注释，还有一种是文档注释。

文档注释

编写任何的代码，都少不了编写程序的文档， 怎么高效的编写文档内容，并且文档的内容能够随着版本的更新进行更新。Java 语言中有一种注释规则， 就是文档注释类型。对于文档注释的内容，是可以通过 Java 内置命令行工具 javadoc 生成对应的文档内容的。并且Java 的 API 也是基于这种机制生成的文档。

使用文档注释的方式 以 /** 开头 */ 结尾。包含在这之内的内容就是文档注释的内容。 而且针对文档注释有一系列的标记。该注释一般会放在 类、方法、变量、常量上。

演示案例：

这里就使用了文档的注释方法， 并且使用了 @author 作者标记， @since 该类从哪个版本开始实现的。

在方法上我们使用了 @param 参数标记， 主要是给参数加上一个说明。

标记分类 “类标记” 和 “方法标记”常用的有以下列表，只是通用这样并不是非要这样写，这样写可以减少再次沟通的成本。

类标记

• @author 代表的是作者是谁，如果有多个，可以写多个标记
• @since 从哪个版本开始支持该类的功能
• @version 当前类的版本信息
• @see 该标记可用在类与方法上，表示参考的类或方法。

方法标记

• @param 参数的描述信息
• @return 当前方法返回的描述信息
• @exception 异常的描述信息，于描述方法 throws 对应的异常
• @throws 描述该方法可能抛出的异常信息，和 @exception 联合使用
• @see 该标记可用在类与方法上，表示参考的类或方法。

当然也有通用的用法, 可以标记上面说的四种类型。

• @code 内容使用代码格式。不会转移显示。
• @link 用于快速的定位到定义的相关类的代码上。使用格式： @link 包名.类名#方法名(参数类型)

把上面的源码生成以下文档， 我们看一下大概的内容。

javadoc -encoding utf-8 -d docs Hello.java

进入到 docs 打开index.html。效果如下：

这样你开发的这个文件的开发文档就编写完成。非常 easy， 非常 nice ! 我们来看看 Java 17 的 Object.java 的源码。

看一下 Java 17 的源码注释

找到安装路径， 然后根目录中找到 lib/src.zip 这个压缩包就是 JDK 17 的源码。

解压这个 src.zip 文件。 因为现在 JDK 都是基于模块开发。 找到基础模块 java.base 并进入到 java.lang 目录， 并找到 Object.java 类。这个是类中之王。 除了基础的类所有的类都默认实现该类。

不需要理解这里面的含义， 只需要理解注释的使用方式。 package 是包名， 后续会针对这个单独开一章， 你可以认为这是一个文件的层次划分。主要是为了解决类名重复的问题。package 上的内容是针对 Java 的开源协议的一个说明。 以后你如果想开源软件， 可以参考这种方式编写你的开源协议内容。

进入到 Java 17 的文档 API 官方页面。

地址为：https://docs.oracle.com/en/java/javase/17/docs/api/index.html

同样的方式进入到 java.base 的模块中。 Java.base 是 Java SE 的基础 API。

进入到 Package 的 java.lang 中。并翻阅到 All Classes and Interfaces 中， 找到 Object。

或者直接进入该地址: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Object.html

可以看到如下界面：

可以看到从版面UI， 还是风格都和 javadoc 生成的一模一样， 从这里也能看出来 Java 的 api 文档，就是使用这种方式进行生成的。 从源码中直接获得注释， 这样你的注释才显得可靠有据。

从该类的描述中我们也能看到 说是 Object 的这个类是所有的类的根类。 也就是后面说所有的对象类都有一个超类。也都继承了该类的相关方法和实现。

扯得有点远了。 先知道有 3 种注释方法， 知道有 Java 的 API 存在， 这篇内容对于初学的你来说。 也就足够了。

后续更多内容。 关注我。