Java 中的注释类型

在 Java 编程中，注释对于使代码易于理解至关重要。注释完全被 Java 编译器忽略，这意味着它们不会增加我们编译后的程序（字节码）的大小，也不会影响我们代码的运行方式。注释的目的是阐明代码的功能，从而促进更好的团队协作和更轻松的维护。

注释的类型

在 Java 中，有以下三种类型的注释：

1. 单行注释
2. 多行（块）注释
3. 文档（javadoc）注释

1. 单行注释（//）

单行注释用于注释代码中的一行。这是注释语句中最常用、最简单的方法。单行注释以一对正斜杠（//）开头。

语法

用途： 适用于对单行程序或小语句进行简短、即时的说明。

快速备注/提醒： 用于 **TODO** 项、**FIXME** 标记或其他与开发相关的提醒。

临时禁用程序： 一种快速**注释掉**程序某一行以进行调试或测试而无需删除它的方法。

示例

注意：我们不能让单行注释跨越多行。

关键特性

• 受行限制： 它不能跨越多行。需要注释的每一行都需要其自己的 //。
• 简洁性： 适用于简短、临时的解释。
• 可读性： 过度使用可能导致**注释污染**，使程序比没有注释时更难阅读。

2. 多行（块）注释（/* ... */）

多行注释用于注释多行代码。它可以用来解释复杂的代码片段，或者一次注释多行代码（因为在那里使用单行注释会很困难）。

多行注释位于 /* 和 */ 之间。 /* 和 */ 之间的任何文本都不会被 Java 执行。

注意：我们不能将一个多行注释放在另一个里面。

语法

何时使用它们？

描述性算法： 当我们需要解释复杂逻辑背后的复杂步骤或推理时。

解释复杂的跨越多行逻辑： 适用于单行注释不足以传达必要上下文或设计选择的场景。

临时隐藏代码： 我们可以在开发或调试期间快速注释掉大段代码，而无需删除它们。

示例：多行注释

让我们看一个示例，说明块注释如何阐明 calculateFactorial() 方法。

输出

120 

3. 文档（Javadoc）注释（/** ... */）

文档注释通常用于为项目或软件应用程序编写大型程序，因为它有助于创建文档 API。这些 API 是为了参考，即代码中使用了哪些类、方法、参数等。它们的内容是结构化的，并经常使用特殊的 **@ 标签**。

要创建文档 API，我们需要使用 javadoc 工具。文档注释位于 /** 和 */ 之间。

语法

关键组件和标签

第一句话充当简洁的摘要，通常在 IDE 或文档表中以简短的工具提示显示。

关键特性

• 结构是关键： Javadoc 工具依赖于标签的精确语法和放置。
• 放置： 必须紧跟在它所描述的类、接口、方法、构造函数或字段的声明之前。
• HTML 友好：我们甚至可以在其中使用基本的 HTML 标签（如 用于强调或

  ...

  用于代码块），以格式化生成的文档。
• 公共 API 要求：在专业环境中，为所有公共和受保护元素提供 Javadoc 是一种强大的最佳实践。它们侧重于 API 的功能以及如何使用它，而不是内部实现细节。
• 首句摘要： Javadoc 工具通常只提取主要描述的第一句话（直到第一个句点后跟空格或换行符）用于摘要表。使其简洁且信息丰富。
• 不用于实现细节： Javadoc 注释应描述公共 API 的功能和使用方法，而不一定描述其内部实现。内部实现细节最好用 // 或 /* ... */ 注释来解释。

为什么需要注释？

• 可读性：它们使程序更容易被任何人阅读，包括我们自己未来的代码。
• 文档：它们解释了程序的目的、工作原理和逻辑。
• 协作：它们通过帮助程序员理解彼此的代码来促进团队合作。
• 调试：它们可用于在测试期间暂时禁用代码段。

有效代码注释的最佳实践

避免冗余注释：如果我们的代码是自解释的，注释只会造成混乱。例如，我们不会注释 int x = 10; // 设置 x 为 10。

避开糟糕的注释：诸如 public void greet() { // 该方法问候用户 System.out.println("Java"); } 之类的注释没有帮助。代码本身已经告诉我们它正在问候用户。如果从方法名或周围代码中不清楚此问候的上下文，则良好的注释会解释为什么会发生此问候或它是哪种类型的问候。

保持简洁明了：直奔主题。我们的注释应一目了然，易于阅读和理解。除非我们的受众是高度专业化的并且正在处理复杂的算法，否则避免使用过于行话的语言。目标是启发，而不是混淆。

使用一致的风格：遵循团队或项目的代码注释风格指南。

为公共 API 使用 Javadoc，为实现细节使用内部注释

/** ... */ 用于我们代码的任何外部用户（其他开发人员、Javadoc 工具）将看到的内容。

/* ... */ 用于解释复杂的内部算法或临时禁用大块代码。

// 用于简短、临时的备注或调试。

结论

注释是编写可维护和协作的 Java 代码不可或缺的一部分。虽然 Java 编译器会忽略它们，但它们的价值在于增强人类的理解，无论是对我们自己还是对其他开发人员。请记住，清晰的代码加上深思熟虑的注释是一位优秀程序员的标志。

Java 注释选择题

1. 要为我们的 Java 代码添加简洁的单行说明，您应该使用内联注释，它以 // 开头。

1. Javadoc
2. 块
3. 内联
4. 多行