【JavaSE专栏9】Java 注释知多少

r囧r小猫 2023-09-24 16:24 76阅读 0赞

> **作者主页**：[Designer 小郑][Designer]  
> **作者简介**：Java全栈软件工程师一枚，来自浙江宁波，负责开发管理公司OA项目，专注软件前后端开发（Vue、SpringBoot和微信小程序）、系统定制、远程技术指导。CSDN学院、蓝桥云课认证讲师，全栈领域优质创作者。热爱技术、专注业务、开放合作、乐于分享，期待你我共同成长！  
> **主打方向**：Vue、SpringBoot、微信小程序

#### 目录 ####

*   *  一、一般注释
     *   *  1.1 块注释
         *  1.2 单行注释
         *  1.3 尾端注释
     *  二、文档注释
     *  三、注释使用规范
     *  四、课时小结

在 Java 中存在两类注释，即一般注释和文档注释，在本文中对齐阐述。

> 注释是指解释字句的文字，也指用文字解释字句。可以是文字符号图片等多种形式。注释，是对书籍或文章的语汇、内容、背景、引文作介绍、评议的文字。

一般注释是同学们在 C 语言中见过的，使用 `/*`、`*/`、`//` 字符界定的注释。

文档注释是 Java 特有的，文档注释可通过 `JavaDoc` 工具转换为 `HTML` 文件。

一般注释用于注释代码或者实现细节。文档注释从实现自由的角度描述代码的规范，手上没有源码的开发者也应可以读懂文档注释。

**注释应该仅包含与阅读和理解程序有关的信息**。

在实战开发中，对设计决策中重要的，或者不是显而易见的地方进行说明是可以的，但应避免提供代码中已经明确表达出来的重复信息，多余的注释很容易过时。

> 提示：频繁的注释是质量较低的代码之一。当你在开发中频繁觉得需要添加注释时，说明你的业务逻辑不太清晰，此时建议重写相关代码。

![在这里插入图片描述][247e50f29a6d4a5a86fea2cfec0a8950.png_pic_center]

--------------------

### 一、一般注释 ###

Java 程序中有 4 种实现注释的风格，如下：

1.  块
2.  单行
3.  尾端
4.  行末

--------------------

#### 1.1 块注释 ####

**块注释通常用于提供对文件、方法、数据结构或算法的阐述**。

块注释被置于每个文件的开始处以及每个方法之前，也可以用于其他地方，比如方法的内部。

在功能和方法内部的块注释应该有相对于的缩进，保持代码整洁，如下所示。

public class Main {
        
    
        public static void main(String[] args) {
        
    
            /**
             * 这是块注释，需要有缩进！
             */
            System.out.println("aa" + "bb");
        }
    }

--------------------

#### 1.2 单行注释 ####

**单行注释可以显示在一行之内**，并和其后的代码具有相同的缩进。

> 提示：如果单行注释不能在一行中写完，则建议使用块注释。

在单行注释之前应该有一个空行，使用单头注释 `//` ，即在代码行的开头进行注释。

单行注释的样例如下所示。

public class Main {
        
    
        public static void main(String[] args) {
        
    
            // System.out.println("aa" + "bb");
        }
    }

--------------------

#### 1.3 尾端注释 ####

**尾端注释用于极短的注释需求**，尾端注释和所要描述的代码块在同一行，但其中要有足够的空格来分开，另外也要注意缩进问题。

尾端注释的样例如下所示。

public class Main {
        
    
        private static final int MAX_SIZE = 10;
        public static void main(String[] args) {
        
    
            System.out.println("aa" + "bb");    /* 尾端注释 A  */
            System.out.println("cc" + "dd");    /* 尾端注释 B  */
        }
    }

--------------------

### 二、文档注释 ###

**文档注释用来描述 Java 的类、接口、构造器、方法、字段**。

每个文档注释都会在 `/**` 和 `*/` 之间，一个文档注释对应一个类、接口或成员，一般用来对类、接口、成员方法、成员变量、静态字段、常量进行说明。

> JavaDoc 工具可以用文档注释自动 HTML 格式的代码文档。

文档注释经常采用一些标签来进行特定的用途或超链接，常用的注释标签如下：

*  **@author**：对类的说明，解释开发该类的作者。
 *  **@version**：对类的说明，解释该类的版本。
 *  **@see**：对类、属性、方法的说明，解释相关主题。
 *  **@param**：对方法的说明，解释方法中的某个参数含义。
 *  **@exception**：对方法的说明，解释方法可能抛出的异常含义。
 *  **@return**：对方法的说明，解释方法返回值的含义。

文档注释样例如下所示：

/**
     * @author Designer 小郑
     * @See https://blog.csdn.net/qq_41464123
     */
    public class Main {
        
    
        private static final int MAX_SIZE = 10;
        public static void main(String[] args) {
        
    
            System.out.println("aa" + "bb");
        }
    }

> javadoc 和 javac、java 一样，是 jdk 的一个工具，只需输入 javac 类目录即可完成 HTML 文件导出。

javac C:\java\git\test\test\Main.java

![在这里插入图片描述][aad5f0a322664fcaa5e22d010c5ecea8.png_pic_center]

--------------------

### 三、注释使用规范 ###

同学们在使用 Java 注释时，需要注意以下规范：

1.  注释应该使代码更为清晰易懂，而不是记日记，也不能描绘思想感情。
2.  注释要当简单明了，能用一句话就不用两句。如果注释太复杂，请检查代码逻辑是否有问题。
3.  注释既要阐述相应代码能做什么，还要解释为什么要这么做和开发约束。
4.  一般的增删改查方法，以及 `get` 和 `set` 方法不需要做注释。
5.  注释不能嵌套，否则编译不能通过。

--------------------

### 四、课时小结 ###

在本课时中，首先讲解了 Java 的注释概念，接着学习了一般注释和文档注释的用法，其中一般注释可分为块注释、单行注释和尾端注释。在下一节课时中，将讲解 Java 的顺序结构语法。  
![在这里插入图片描述][79344384aaaf4b7894f44cd11718c126.gif_pic_center]

[Designer]: https://blog.csdn.net/qq_41464123
[247e50f29a6d4a5a86fea2cfec0a8950.png_pic_center]: https://img-blog.csdnimg.cn/247e50f29a6d4a5a86fea2cfec0a8950.png#pic_center
[aad5f0a322664fcaa5e22d010c5ecea8.png_pic_center]: https://img-blog.csdnimg.cn/aad5f0a322664fcaa5e22d010c5ecea8.png#pic_center
[79344384aaaf4b7894f44cd11718c126.gif_pic_center]: https://img-blog.csdnimg.cn/79344384aaaf4b7894f44cd11718c126.gif#pic_center