Java学习之旅第一季-6：注释-优快云博客

6.1 注释概述

注释本身不提供功能，它是对程序中代码的说明与解释，Java 编译器会忽略它们。它们被包含在源代码中，用于描述程序代码的功能和逻辑。在实际开发中，也经常将由于各种原因不希望运行的代码作为注释。

Java支持三种类型的注释：

单行注释：以 // 开头，只能注释一行
多行注释：以 /* 开头，以 */ 结尾，可以注释一行或多行
文档注释：以 /** 开头，以 */ 结尾，对类，方法等进行注释，利用javadoc命令可以产生Java API文档

6.2 单行注释

顾名思义，单行注释可以在一行中的任意位置开始。从两个正斜杠到行尾的部分被视为注释。如：

public class HelloJava25 {
    //以下是Java 25支持的新语法
    void main() {
        //在控制台输出Hello Java 25!
        System.out.println("Hello Java 25!"); //在控制台输出Hello Java 25!
    }
}

但是要注意，这种类型的注释不能插入到 Java 代码的中间。比如以下代码第3行的写法是不正确的，因为方法名也被视为注释的一部分：

public class HelloJava25 {
    //以下是Java 25支持的新语法
    void //这是主方法 main() {
        //在控制台输出Hello Java 25!
        System.out.println("Hello Java 25!");
    }
}

6.3 多行注释

多行注释可以跨越多行。它以以 /* 开头，以 */ 结尾。如：

public class HelloJava25 {
    /*
        以下是Java 25支持的新语法
        在老版本的JDK中是无法作为程序运行入口的
     */
    void main() {
        /*
        System.out.println("Hello Java 25!");
        System.out.println("Hello Java 25!");
        */
    }
}

上面的代码片段体现了多行注释的两种常用场景：

2-5行：注释内容比较多需要多行才能比较好的展示
7-10行：暂时不希望执行的代码（可能暂时有bug或在测试时想先省略这些功能）可以使用注释达到既不执行又保存在源码中的效果，实际开发中很常用。

多行注释可以插入到 Java 代码的中间部分，如下代码第1行所示。编译器会忽略从 /* 开头，以 */ 之间的所有内容：

public class /* 声明类 */ HelloJava25 {
    /*
        以下是Java 25支持的新语法
        在老版本的JDK中是无法作为程序运行入口的
     */
    void main() {
        /*
        System.out.println("Hello Java 25!");
        System.out.println("Hello Java 25!");
        */
    }
}

当然这种写法极少使用。

6.4 文档注释

首先文档注释是一种多行注释，不用之处在于它是以 /**开头。其主要目的是为程序产生文档。

由于文档注释中支持大量的标签，且大量使用在类和方法上，这里不做过多介绍，完整的标签使用可参考：Java文档注释使用指南

/**
 * 声明类HelloJava25
 *
 * @author 老谭
 */
public class HelloJava25 {
    void main() {
        System.out.println("Hello Java 25!");
    }
}

说明：

1-5行就是用于类上的文档注释，当输入打回车，IDEA就自动产生文档注释，2-4行都以开头，并无实际意义。
第2行是对当前类的描述
第4行的@author使用一个标签，后面跟上该类的作者

下面我们看看如何文档注释的效果。

场景1、无论在什么情况下使用该类时，将光标悬停在类名上，就会弹出刚才注释中的内容：

场景2、使用JDK的javadoc命令可以产生网页格式的API文档，为了方便，我直接使用IDEA来实现次功能。

IDEA产生文档2

产生之后，在指定的目录下会产生若干网页，默认会打开首页。

IDEA产生文档3

点击类名，打开的页面信息更详细。

IDEA产生文档4

6.5 IDEA产生注释的快捷键

在IDEA 中，单行注释的快捷键是 Ctrl + /。这个快捷键可以快速地为当前光标所在行添加注释。如果你想对多行代码进行单行注释，只需选中这些代码行，然后按下 Ctrl + / 即可，则会对每一行产生以个单行注释。

如果当前行有单行注释，按下 **Ctrl + /**则会移除这行的当行注释。

如果需要添加多行注释，可以使用 Ctrl + Shift + / 快捷键。这将在选中的代码块前后分别添加/* 和*/来创建一个多行注释块。

要移除多行注释，只需将光标放在注释内部并按下 Ctrl + Shift + / 即可。

6.6 小结

本小节介绍了注释的概念，Java中注释的三种类型，最后介绍了IDEA中针对注释的快捷键。