注释

什么是注释

注释是开发者在源代码中插入的‌自然语言说明文字‌，用于解释代码的目的、逻辑、设计思路或其他相关信息。编译器在编译源代码时，会‌完全忽略‌代码中的所有注释，也就是说注释的内容不会出现在最终的程序中，也不会影响程序的性能和执行逻辑。注释就像是嵌入在代码里的“说明书”，核心目的是为了提高代码的可读性和可维护性。

注释的分类

单行注释

以 // 开头，并且只对当前行有效

// 这是一个单行注释
int age = 18;  // 这里也可以添加单行注释

多行注释

以 /* 开头，以 */ 结尾，可以跨越多行

/*
这是一个多行注释
可以写很多行内容
*/

文档注释

以 /** 开头，以 */ 结尾，用于生成 API 文档

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

注释的最佳实践

• ‌解释复杂逻辑：注释应聚焦算法设计、业务规则等非直观逻辑，避免描述显而易见的代码，比如 i++ // 使 i 增加 1。
• 保持注释与代码同步更新：修改代码时同步更新注释，避免产生误导性信息，因为过时注释可能比没有注释更加危险‌。
• ‌文档注释：类、字段、方法应该使用文档注释（使用标准标签，比如 @param @return 等），从而可以使其在 IDE 中得到更好的提示。