滚雪球学Java(10)：Java注释

  咦咦咦，各位小可爱，我是你们的好伙伴——bug菌，今天又来给大家普及Java SE相关知识点了，别躲起来啊，听我讲干货还不快点赞，赞多了我就有动力讲得更嗨啦！所以呀，养成先点赞后阅读的好习惯，别被干货淹没了哦~

🏆本文收录于 **[「滚雪球学Java」 ](https://blog.csdn.net/weixin_43970743/category_9600553.html)专栏，专业攻坚指数级提升，希望能够助你一臂之力，帮你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅**！持续更新中，up！up！up！！

环境说明：Windows 10 + IntelliJ IDEA 2021.3.2 + Jdk 1.8

前言

在编写代码时，注释一直被认为是良好编程实践的一部分。注释可以帮助提高代码的可读性，减少代码的维护成本，同时也是文档化代码的一种方式。本文将介绍Java中的注释类型及其用法。

摘要

本文将讨论Java中的三种注释类型：单行注释，多行注释和文档注释，并提供一些最佳实践和示例。

内容

单行注释

单行注释以//开头，从//开始到行尾为注释内容。单行注释通常用于解释代码行的作用。下面是一个单行注释的例子：

int i = 0; // 初始化i为0

多行注释

多行注释以/*开头，后跟多行注释内容，以*/结尾。多行注释通常用于解释代码块或更长的代码段。下面是一个多行注释的例子：

/*
这是一个多行注释的例子
它用于解释更长的代码段
*/
int j = 1;

文档注释

文档注释以/**开头，后跟文档注释内容，以*/结尾。文档注释通常用于生成API文档。文档注释应该包含类、接口、方法和字段的描述、参数、返回值等信息。下面是一个文档注释的例子：

/**
* 这个类用于计算两个数的和、差、积和商
*/
    public static class Calculator {
        /**
         * 计算两个数的和
         *
         * @param x 第一个操作数
         * @param y 第二个操作数
         * @return 两个数的和
         */
        public int add(int x, int y) {
            return x + y;
        }
    }

代码解析：

  这段代码定义了一个名为Calculator的类，用于计算两个数的和、差、积和商。该类中有一个公有方法add，用于计算两个数的和。

  add方法有两个输入参数x和y，分别代表第一个操作数和第二个操作数。方法的返回类型是int，表示返回一个整数结果。在方法体中，通过将两个操作数相加，得到它们的和，并将结果返回。

  该类还可继续扩展，添加计算差、积和商的方法。

最佳实践

以下是一些注释的最佳实践：

• 尽可能使用文档注释来生成API文档。
• 尽管单行注释可以在代码行旁边解释代码，但应避免在代码的末尾使用单行注释，因为在调整代码行时可能会忘记更新注释。
• 在多行注释中，应该避免使用嵌套注释，因为这可能会使注释更难阅读。

示例

以下是一个Java程序，它计算并打印两个数字的和：

package com.demo.javase.day10;

/**
 * @Author bug菌
 * @Date 2023-12-27 14:41
 */
public class DocTest {

    public static class Calculator {
        /**
         * 计算两个数的和
         *
         * @param x 第一个操作数
         * @param y 第二个操作数
         * @return 两个数的和
         */
        public int add(int x, int y) {
            return x + y;
        }
    }

    /**
     * 主函数
     */
    public static void main(String[] args) {
        // 创建计算器对象
        Calculator calculator = new Calculator();
        // 计算两个数的和
        int sum = calculator.add(2, 3);
        // 打印和
        System.out.println("2 + 3 = " + sum);
    }
}

代码解析：

  该代码是一个简单的计算器类，其中包括一个add方法用来计算两个数的和。该方法接受两个整数参数x和y，并返回它们的和。

  在主函数中，首先创建了一个Calculator对象calculator，然后调用其add方法计算2和3的和，并将结果赋给变量sum。最后通过System.out.println方法打印出计算结果。运行该程序，输出结果为"2 + 3 = 5"。

执行结果如下：

代码方法介绍

本程序中定义了一个Calculator类，它有一个add方法和一个main方法：

• add方法用于计算两个数的和并返回结果。
• main方法是程序的起点，它创建一个计算器对象，并调用add方法计算两个数字的和。最后，它打印和的结果。

测试用例

为了测试Calculator类的add方法，我们可以编写以下测试用例：

import org.junit.Assert;
import org.junit.Test;

public class CalculatorTest {

  @Test
  public void addTest() {
    Calculator calculator = new Calculator();
    int sum = calculator.add(2, 3);
    Assert.assertEquals(5, sum);
  }
}

该测试用例使用JUnit框架编写。它创建一个Calculator对象，调用add方法并断言返回值是否等于预期值5。

代码解析：

  这是一个使用JUnit进行单元测试的测试类。测试类中包含了一个测试方法addTest()，用于测试Calculator类的add()方法。

  首先，我们创建了一个Calculator对象。然后，调用add()方法，传入参数2和3，并将结果赋值给变量sum。

  接着，使用JUnit提供的Assert类的assertEquals()方法进行断言。assertEquals()方法用于比较两个值是否相等。这里我们比较sum的值是否等于5。如果相等，测试通过；如果不相等，测试失败。

  在进行单元测试时，我们通常会编写一些测试用例，测试各种情况下的输入和输出。这个例子中，我们只测试了一种情况，即2加3的结果是否等于5。实际应用中，我们需要编写更多的测试用例，以覆盖更多的情况。

执行测试结果如下：

全文小结

本文介绍了Java中的三种注释类型：单行注释，多行注释和文档注释。我们还提供了一些注释的最佳实践和示例。通过本文的学习，您应该能够更好地理解Java注释的使用和作用，从而提高自己的编程能力。

  ... ...

  好啦，这期的内容就基本接近尾声啦，若你想学习更多，你可以看看专栏的导读篇《「滚雪球学Java」教程导航帖》，本专栏致力打造最硬核 Java 零基础系列学习内容，🚀打造全网精品硬核专栏，带你直线超车；欢迎大家订阅持续学习。功不唐捐，久久为功！

「赠人玫瑰，手留余香」，咱们下期拜拜~~

☀️建议/推荐你

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学Java」，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门Java编程，就像滚雪球一样，越滚越大，指数级提升。

  码字不易，如果这篇文章对你有所帮助，帮忙给bugj菌来个一键三连(关注、点赞、收藏) ，您的支持就是我坚持写作分享知识点传播技术的最大动力。   同时也推荐大家关注我的硬核公众号:「猿圈奇妙屋」 ；以第一手学习bug菌的首发干货，不仅能学习更多技术硬货，还可白嫖最新BAT大厂面试真题、4000G Pdf技术书籍、万份简历/PPT模板、技术文章Markdown文档等海量资料，你想要的我都有！

📣关于我

  我是bug菌，CSDN | 掘金 | infoQ | 51CTO 等社区博客专家，历届博客之星Top30，掘金年度人气作者Top40，51CTO年度博主Top12，华为云 | 阿里云| 腾讯云等社区优质创作者，全网粉丝合计15w+ ；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试题、4000G pdf电子书籍、简历模板等海量资料。

--End

我正在参与2024腾讯技术创作特训营最新征文，快来和我瓜分大奖！