【Java SE 基础学习打卡】14 Java 注释

目录

• 前言
• 一、先明白：啥是注释？为啥非要写？
• [二、Java 的三种注释：单行、多行、文档注释](#二、Java 的三种注释：单行、多行、文档注释)
• • [2.1 单行注释：一行代码的 "小提示"](#2.1 单行注释：一行代码的 “小提示”)
  • [2.2 多行注释：多段代码的 "详细说明"](#2.2 多行注释：多段代码的 “详细说明”)
  • [2.3 文档注释：能生成 "官方说明书" 的高级注释](#2.3 文档注释：能生成 “官方说明书” 的高级注释)
• [三、实用技能：用 javadoc 生成官方风格文档](#三、实用技能：用 javadoc 生成官方风格文档)
• • [3.1 第一步：准备好带文档注释的代码](#3.1 第一步：准备好带文档注释的代码)
  • [3.2 第二步：打开 CMD，进入代码所在文件夹](#3.2 第二步：打开 CMD，进入代码所在文件夹)
  • [3.3 第三步：输入 javadoc 命令](#3.3 第三步：输入 javadoc 命令)
  • [3.4 第四步：查看生成的文档](#3.4 第四步：查看生成的文档)
• [四、新手写注释的 3 个小建议](#四、新手写注释的 3 个小建议)
• 总结

前言

刚开始写 Java 代码的小伙伴，可能会觉得 "注释没啥用，把代码写对就行"------ 但等你过一周回头看自己的代码，或者跟别人合作写项目时就会发现：没有注释的代码，就像没贴标签的快递，根本不知道里面装的啥。其实注释就是代码的 "说明书"，能帮你和别人快速看懂代码逻辑。这一节咱们就把 Java 注释讲透：先搞懂为啥要写注释，再学会三种注释的写法，最后知道怎么用注释生成官方风格的文档 ------ 全程用例子说话，一看就会。

一、先明白：啥是注释？为啥非要写？

咱们先从生活中的例子理解 "注释"：你买了一本旅行指南，里面除了景点介绍，还会有 "建议早上去人少""附近有隐藏美食" 这样的小字提示 ------ 这些提示就是 "注释"，不是必须的，但能帮你更好地规划行程。

编程里的注释也一样：它是写在代码里的 "说明文字"，编译器会自动忽略它（不会影响程序运行），但能帮人理解代码。比如你写了一段复杂的计算逻辑，加一句注释说明 "这步是算用户总积分"，别人一看就懂，不用盯着代码猜半天。

为啥说注释很重要？看看程序员的 "心声" 就懂了

有个笑话是 "程序员最讨厌两件事：别人不写注释，以及自己要写注释"------ 这背后其实藏着注释的必要性：

1. 帮自己记事儿：今天写的代码逻辑，过一个月可能就忘了；加了注释，回头看一眼就知道 "当时为啥这么写"，不用重新推导。

2. 方便团队合作：如果跟同学一起做项目，你写的函数加了注释，他不用问你就能直接用；没注释的话，他可能得花半小时猜你的代码功能。

3. 降低维护难度：代码出 bug 要修改时，有注释能快速定位关键逻辑，不用从头到尾读代码；没有注释的话，改代码就像 "拆盲盒"，很容易改出新问题。

4. 倒逼自己理清思路：写注释的过程，也是梳理代码逻辑的过程 ------ 如果写不出注释，可能说明你自己都没搞懂这段代码要干嘛，刚好能及时发现问题。

简单说：注释不是给电脑看的，是给 "人" 看的 ------ 包括未来的你自己。

二、Java 的三种注释：单行、多行、文档注释

Java 里有三种注释方式，分别对应不同的使用场景，咱们一个个学，都很简单：

2.1 单行注释：一行代码的 "小提示"

用法 ：用//开头，后面跟注释内容，只作用于当前行。

场景：解释某一行代码的功能，或者临时注释掉某行不用的代码。

举个例子：

// 单行注释：向控制台打印"Hello World"（这行是说明，不会被执行）
System.out.println("Hello World!");

// 单行注释：下面这行代码暂时不用，注释掉就不会运行了
// System.out.println("这行代码被注释了，不执行");

小技巧：单行注释最好写在要解释的代码上方，或者右侧（如果代码不长），别写得太乱 ------ 比如这样就很清晰：

// 计算长方形面积（长*宽）
int area = length * width; // 面积结果存到area变量里

2.2 多行注释：多段代码的 "详细说明"

用法 ：用/*开头，*/结尾，中间可以写多行内容。

场景：解释一个代码块（比如一个方法、一段循环逻辑），或者临时注释掉多段不用的代码。

举个例子：

/*
 * 多行注释：这里是Java程序的入口方法main
 * 作用：程序启动后，会从这个方法开始执行
 * 注意：main方法的格式是固定的，不能随便改
 */
public static void main(String[] args) {
    // 单行注释：打印欢迎信息
    System.out.println("欢迎学习Java注释！");
}

注意点 ：多行注释不能 "嵌套"------ 就是不能在/* */里面再写/* */，比如下面这样会报错：

/*
  错误示例：多行注释里嵌套了另一个多行注释
  /* 这行注释会导致语法错误 */
*/

另外，多行注释还能帮你调试 bug：比如程序出错了，你可以用/* */注释掉部分代码，再运行看看错误是否消失，逐步定位问题在哪段代码里 ------ 这是新手常用的调试小技巧。

2.3 文档注释：能生成 "官方说明书" 的高级注释

用法 ：用/**开头，*/结尾，比多行注释多一个*，常放在类、方法、变量的上方。

特殊功能 ：可以用@author（作者）、@version（版本）、@param（参数）等标签，再通过 JDK 的javadoc工具，自动生成像官方文档一样的 HTML 页面 ------ 以后你写的代码想给别人用，生成这种文档会特别专业。

举个例子（给类加文档注释）：

/**
 * 文档注释：这是一个打印Hello World的简单类
 * @author 编程小白（标注作者）
 * @version 1.0（标注版本）
 * @since 2023/7/7（标注创建时间）
 */
public class HelloWorld {
    /*
     * 多行注释：main方法是程序入口
     */
    public static void main(String[] args) {
        // 单行注释：打印输出
        System.out.println("Hello World!");
    }
}

再举个给方法加文档注释的例子（以后学方法会常用）：

/**
 * 文档注释：计算两个整数的和
 * @param a 第一个整数（说明参数含义）
 * @param b 第二个整数（说明参数含义）
 * @return 两个整数相加的结果（说明返回值）
 */
public static int add(int a, int b) {
    return a + b;
}

三、实用技能：用 javadoc 生成官方风格文档

咱们写的文档注释，光放在代码里还不够 ------ 用 JDK 自带的javadoc命令，能把这些注释提取出来，生成像 Oracle 官网那样的 API 文档（HTML 页面），别人打开浏览器就能看，特别方便。

咱们以HelloWorld.java为例，一步步操作：

3.1 第一步：准备好带文档注释的代码

确保你的HelloWorld.java里有完整的文档注释（比如前面加了@author、@version的注释）。

3.2 第二步：打开 CMD，进入代码所在文件夹

按Win+R输cmd打开 CMD，用cd命令进入HelloWorld.java所在的文件夹。

3.3 第三步：输入 javadoc 命令

在 CMD 里输下面的命令，按回车：

javadoc -d docs HelloWorld.java

• javadoc：调用生成文档的工具；

• -d docs：指定生成的文档存到一个叫 "docs" 的文件夹里（没有这个文件夹会自动创建）；

• HelloWorld.java：要生成文档的源代码文件。

3.4 第四步：查看生成的文档

命令执行完后，去代码所在文件夹里找 "docs" 文件夹，打开后会看到一堆 HTML 文件 ------ 双击index.html，就能在浏览器里看到生成的官方风格文档了，你写的文档注释会清晰地显示在对应位置。

以后你写的代码想给别人用，直接把这个 "docs" 文件夹发给对方，他就能像查 Java 官方文档一样，快速了解你的代码功能 ------ 这是专业程序员的必备技能。

四、新手写注释的 3 个小建议

刚开始写注释可能会不知道写啥，记住这 3 个建议，能帮你少走弯路：

1. 注释要 "说原因，不是说结果" ：比如写// 计算用户总积分（购物积分+签到积分），比写// 计算总和有用 ------ 前者解释了逻辑，后者只是重复代码功能。

2. 注释要跟代码 "同步更新" ：如果改了代码逻辑（比如把 "购物积分2" 改成 "购物积分1.5"），一定要同步改注释 ------ 过时的注释比没有注释更坑人，会误导别人。

3. 别过度注释 ：简单的代码不用加注释（比如int age = 18;），复杂逻辑、特殊处理才需要加 ------ 比如循环里的条件判断、方法的参数含义，这些才是注释的重点。

总结

学完这一节，你只要记住 3 个关键点：

1. 注释是代码的 "说明书"，帮人理解逻辑，不影响程序运行，一定要养成写注释的习惯；

2. Java 有三种注释：单行注释（//）适合单句说明，多行注释（/* */）适合多段解释，文档注释（/** */）能生成官方文档；

3. 用javadoc命令能把文档注释生成 HTML 文档，方便别人查看你的代码功能。

从现在开始，写代码时就试着加注释吧 ------ 刚开始可能觉得麻烦，但坚持下来，你会发现不管是自己复习还是跟人合作，都会轻松很多！