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

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

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

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

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

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

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

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

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

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

在这里插入图片描述


一、一般注释

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

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

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

在这里插入图片描述


三、注释使用规范

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

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

四、课时小结

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

猜你喜欢

转载自blog.csdn.net/qq_41464123/article/details/128765336
今日推荐