【Java 基础】06 注释

当编写代码很少，没有几行的时候我们可以很容易知道代码的含义。但是随着代码行数的增加，逻辑复杂性的增加就不容易看出代码的含义了，就需要我们逐行阅读分析。

1.注释是什么？

注释就是一种特殊的代码

它是起到提示作用的，和具体的逻辑没有任何关系。在编写代码时，使用注释去说明代码逻辑，良好的注释是代码可读性和可维护性的关键。

2.注释的种类

1）单行注释

单行注释以 // 开始，可以在一行代码的末尾添加注释

// 这是一个单行注释
int x = 9; // 初始化变量 x

2）多行注释

多行注释以 /* 开始，以 */ 结束，可以跨越多行

/*
 * 这是一个多行注释
 * 可以包含多行文字
 */
int x = 10;

3）文档注释

文档注释以 /** 开始，以 */ 结束，用于生成API文档。通常用于类、方法、字段的说明

/**
 * 这是一个文档注释
 */
public class Test {
    /**
     * 这是一个文档注释
     * @param num1 数1
     * @param num2 数2
     * @return 传入两个数的和
     */
    public int sum(int num1, int num2) {
        return num1 + num2;
    }
}

3. 注释标签

注释标签主要用于编写 文档注释（Javadoc），以生成API文档。

以下是常用的文档注释标签：

@param：

用于描述方法的参数

/**
 * 计算两个数的和
 * @param a 第一个数
 * @param b 第二个数
 * @return 两个数的和
 */
public int add(int a, int b) {
    return a + b;
}

@return

用于描述方法的返回值

/**
 * 获取姓名
 * @return 姓名字符串
 */
public String getName() {
    return name;
}

**@throws **

@exception

@throws 和 @exception 用于描述方法可能抛出的异常

/**
 * 读取文件内容
 * @param filePath 文件路径
 * @throws IOException 如果读取文件时发生I/O异常
 */
public String readFile(String filePath) throws IOException {
    // 读取文件的代码
}

@deprecated

用于标记方法、类或字段已经不推荐使用，通常伴随着一段描述替代方案的说明

/**
 * @deprecated 不推荐使用，请使用新的方法 {@link #newMethod()}
 */
@Deprecated
public void oldMethod() {
    // 旧方法的实现
}

@see

用于提供对其他类、方法或字段的引用

/**
 * 查看 {@link OtherClass} 类的文档
 */
public void seeOtherClass() {
    // ...
}

@link

与@see类似，用于创建超链接

/**
 * 请参考 {@link #add(int, int)} 方法
 */
public void referToAddMethod() {
    // ...
}

@inheritDoc

用于继承文档注释，表示子类或实现类应该继承父类或接口的文档注释

/**
 * {@inheritDoc}
 * 新增了一些额外的说明
 */
@Override
public void someMethod() {
    // 实现方法
}

这些注释标签在Javadoc中被解析，并用于生成详细的API文档，帮助开发者理解和使用代码。使用这些标签可以提高文档的质量，使得生成的文档更加详尽和规范。

总结：通过运用不同类型的注释，我们能够更好地组织和解释代码，使得代码更易读、易懂。在实际开发中，良好的注释是团队协作和代码维护的关键。