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

news2024/10/6 18:24:27

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

一、一般注释

Java 程序中有 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");
    }
}