第5章 Java注释

面包屑导航章节头部学习目标

学习目标

掌握Java中三种注释类型的语法和使用场景
学会使用单行注释（//）进行代码说明
理解多行注释（/* */）的适用情况
掌握文档注释（/** */）和Javadoc标签的使用
了解注释的最佳实践和常见误区
学会为代码编写高质量的注释

注释类型详解

Java注释类型详解

在Java编程中，注释是一种重要的代码文档化手段。Java支持三种类型的注释，每种都有其特定的用途和语法。良好的注释习惯能够显著提高代码的可读性和可维护性。

单行注释（//）

// 这是单行注释
int count = 0; // 也可以在代码后面添加注释

用于简短的代码说明
解释单行代码的作用
临时注释掉代码
添加TODO或FIXME标记

多行注释（/* */）

/*
 * 这是多行注释
 * 可以跨越多行
 * 适合较长的说明
 */

适合较长的说明文字
临时注释掉大段代码
版权声明和许可信息
复杂算法的详细说明

文档注释（/** */）

/**
 * 这是文档注释
 * 用于生成API文档
 * 
 * @param name 参数说明
 * @return 返回值说明
 */

生成Javadoc API文档
类和方法的详细说明
支持HTML标签和特殊标签
IDE智能提示支持

Javadoc标签详解

Javadoc提供了丰富的标签来描述代码的各个方面，这些标签能够生成结构化的API文档。

标签	说明	使用示例
@author	作者信息	@author 张三
@version	版本信息	@version 1.0
@since	起始版本	@since JDK 1.8
@param	参数说明	@param name 用户姓名
@return	返回值说明	@return 用户对象
@throws	异常说明	@throws IllegalArgumentException
@see	参考链接	@see String
@deprecated	已废弃标记	@deprecated 使用newMethod()替代

代码示例

完整代码示例

/**
 * Java注释示例程序
 * 演示三种注释类型的使用方法
 * 
 * 这是一个文档注释，用于生成API文档
 * 通常用于类、方法和重要字段的说明
 * 
 * @author Java学习者
 * @version 1.0
 * @since 2024-01-05
 */
public class CommentExample {
    
    // 这是单行注释，用于简短的说明
    // 通常用于解释代码的作用或注意事项
    private String name;
    
    /*
     * 这是多行注释
     * 可以跨越多行
     * 适合较长的说明文字
     * 或者临时注释掉一段代码
     */
    private int age;
    
    /**
     * 构造方法 - 创建CommentExample对象
     * 
     * @param name 姓名，不能为空
     * @param age 年龄，必须大于0
     */
    public CommentExample(String name, int age) {
        this.name = name;  // 设置姓名
        this.age = age;    // 设置年龄
    }
    
    /**
     * 获取姓名
     * 
     * @return 返回当前对象的姓名
     */
    public String getName() {
        return name;
    }
    
    /**
     * 显示个人信息
     * 
     * 这个方法会在控制台输出格式化的个人信息
     * 包括姓名和年龄
     */
    public void displayInfo() {
        // 输出分隔线
        System.out.println("=== 个人信息 ===");
        
        // 输出姓名和年龄
        System.out.println("姓名: " + name);
        System.out.println("年龄: " + age + "岁");
        
        /*
         * 可以在这里添加更多信息
         * 比如出生年份计算等
         */
    }
}

💻 查看完整代码 - 在线IDE体验注释最佳实践

注释最佳实践

注释编写原则

好的注释

// 使用二分查找提高搜索效率
int index = binarySearch(array, target);

// 根据用户等级计算折扣：VIP用户享受8折优惠
double discount = user.isVip() ? 0.8 : 1.0;

/**
 * 计算两个整数的和，处理溢出情况
 * 
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两数之和
 * @throws ArithmeticException 当计算结果溢出时
 */

解释"为什么"而不是"是什么"
说明复杂的业务逻辑
解释算法和公式
标注重要的注意事项

不好的注释

// 将i设置为0
int i = 0;

// 连接MySQL数据库（实际已改为PostgreSQL）
connection = getConnection();

// 开始
start();

重复代码内容
过时的注释
无意义的注释
过度注释显而易见的代码

注释规范建议

注释编写规范保持同步：注释与代码同步更新，避免过时信息语言清晰：使用简洁明了的语言，避免歧义适度原则：避免过度注释，重点关注复杂逻辑统一风格：团队内保持一致的注释风格及时清理：删除无用和过时的注释

常见注释误区注释与代码不一致，产生误导为显而易见的代码添加无意义注释使用注释来弥补糟糕的代码设计注释中包含错误或过时的信息过度依赖注释而忽视代码自文档化

本章小结

Java支持三种注释类型：单行注释（//）、多行注释（/* /）和文档注释（/* */）
单行注释适合简短说明，多行注释适合较长描述，文档注释用于生成API文档
Javadoc提供了丰富的标签来描述代码的各个方面
好的注释应该解释"为什么"而不是"是什么"
注释应该与代码保持同步，避免过时和误导信息
适度使用注释，重点关注复杂逻辑和业务规则
建立团队统一的注释规范和风格

导航链接上一章：第一个Java程序章节测试下一章：Java数据类型 JavaScript