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 存在，这篇内容对于初学的你来说。也就足够了。

后续更多内容。关注我。

前军教程网

中小站长与DIV+CSS网页布局开发技术人员的首选CSS学习平台

Java17中的注释方式