Java学习笔记系列-基础篇- Java中的注释与文档

最新推荐文章于 2023-03-19 16:12:38 发布

klsstt

最新推荐文章于 2023-03-19 16:12:38 发布

阅读量266

点赞数

分类专栏： Java学习笔记系列 Java 文章标签： java

本文链接：https://blog.youkuaiyun.com/klsstt/article/details/115864229

版权

Java 同时被 2 个专栏收录

24 篇文章

订阅专栏

Java学习笔记系列

14 篇文章

订阅专栏

本文是Java学习笔记的基础篇，介绍了Java中的注释类型及其作用，包括单行注释、多行注释和文档注释。讲解了注释的实现原理，并通过实例展示了如何使用Javadoc生成API文档。强调了良好注释对于代码可读性和维护性的重要性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Java学习笔记

Java学习笔记是一个持续更新的系列，工作多年，抽个空对自身知识做一个梳理和总结归纳，温故而知新，同时也希望能帮助到更多正在学习Java 的同学们。

本系列目录

入门篇

基础篇

Java中的注释

程序中的注释主要是对代码的解释和说明，其目的是让人们能够更加轻松地了解代码。

文学作品中的注释，是用来指解释字句的文字，而重程序中的注释，是用来解释代码含义，以提高程序代码的可读性。

注释实现原理

Java编译器通过特殊符号识别和区分代码与注释，被注释的部分不会进行编译。

我们在入门篇中介绍过高级语言的实现原理即通过翻译程序，将高级语言编写的程序翻译成机器可识别的程序，才能被计算机识别和执行，而注释就是翻译程序不会进行翻译的部分内容。

在Java语言中，注释分别有三种用法

单行注释
多行注释
文档注释

在IDEA中，打开上一节我们创建的HelloWord.java文件，添加一些注释内容，如下：

package com.klsstt.test;

/**
 * @author klsstt
 * @version v0.1
 * 我是文档注释
 */
public class HelloWrod {
    /**
     * 这是main方法
     * @param args 默认参数
     */
    /*
        我是多行注释
     */
    public static void main(String[] args) {
        /*
        我也是多行注释
        */
        //我是单行注释
        //System.out.println("我是单行注释!");
        System.out.println("Hello Word!");
    }
}

我在main方法中，注释了一行代码，如果注释无效，代码会在程序编译之后运行并输出“我是单行注释!”，之后会输出“Hello Word!”，运行该程序观察结果。
在这里插入图片描述
控制台中只输出了“Hello Word!”，证明我们这行代码在被编译器翻译的过程中被忽略了。

单行注释

顾名思义，对单行进行的注释，以//开始，也可以用来对某一行代码进行注释。
被注释的代码在编译过程中会被忽略，例如上述案例中的 //System.out.println("我是单行注释!");，我们通常使用单行注释对某一行的代码、变量具备的业务内容进行说明。

多行注释

/*开始，*/结束为多行注释，在多行注释中，可以输入多行内容，但是内容中不能嵌套多行注释，负责编译器会报错。

编译器只能识别第一个/*和第一个*/的符号，就会认为注释结束，如果后面还有注释则认为是错误代码。
错误示范：/* /* 嵌套注释 */ */

文档注释

/**开始，*/结束，文档注释就比多行注释开头多了一个*，但是与多行注释作用完全不同。

文档注释是可以被JDK提供的javadoc工具所识别的一种注释，按照规定的要求进行书写的文档注释可以使用javadoc工具生成一套HTML版本的说明文档。

javadoc.exe在JDK的bin目了下，可以使用命令行javadoc -d 文件夹名称作者文件路径生成html说明文档。

在IDEA中如何生成javadoc说明文档呢，打开工具栏Tools->Generate JavaDoc
在这里插入图片描述
打开之后，会弹出JavaDoc配置窗口，配置内容如下

注意：使用了注解@author和@version需要在配置中勾选，否则生成的文档中不会携带对应的信息，我这里截图是未勾选的情况。

参数说明：

Generate JavaDoc scope
选择生成的文档范围，可以对整个工程生成javadoc，也可以针对某一个文件，一个模块进行，这个根据实际工作情况来定，我们这块只需要选择HelloWord.java这个文件即可。
Locale
语言选项，国内就填写zh_CN即可。
Other command line arguments
其他参数选项，主要用来设置编译文件的编码
```
-encoding UTF-8 -charset UTF-8 
```

配置完成之后选择好输出路径，点击OK即可弹出生成好的文档页面。
在这里插入图片描述
点击HelloWord，即可看到类与方法的文档内容描述

被我用红圈圈起来的地方就是我们的文档注释内容，我们再来看看这段代码

 /**
     * 这是main方法
     * @param args 默认参数
     */
    /*
        我是多行注释
     */
    public static void main(String[] args) {
        /*
        我也是多行注释
        */
        //我是单行注释
        //System.out.println("我是单行注释!");
        System.out.println("Hello Word!");
    }

通过比较文档注释和多行注释我们会发现，只有文档注释被javadoc识别，多行注释内容无法被识别。

Java中的API文档

Java API文档是官网提供的一个开发帮助文档，也是通过javadoc生成的一个JDK说明文档，这个文档也是我们在接触学习Java必读文档。

Java8文档官网地址:

https://docs.oracle.com/javase/8/docs/api/

打开这个文档链接，我们发现其风格和我们自己用javadoc生成的文档风格一致，说明JavaJDK在开发过程中大量使用了javadoc注释，也为我们开发过程形成了一种良好的示范。
在这里插入图片描述
整个文档按照路径分为三个区域

packages
包列表区域，优先展示类的包路径，点击之后展示包里所有类
all classes
类列表区域，默认展示所有类，选择指定包名之后，只展示包内类列表
class
类详细说明区域，选择某个类之后，展示其详细信息

结语

随着业务变迁，我们开发的项目可能越来越庞大，而且IT行业人员变动频繁，如果代码书写没有详细的注释和说明文档，这对其他交接人来说无疑是痛苦的，而且，时间久了，自己写过的代码可能都会忘记，这时候有一个详细的注解或者说明文档，无疑是幸福的，如果你是刚开始学习Java的话，那么从现在开始就培养自己形成一个好的编码习惯吧。