如何在 Java 中编写注释

了解有关 Java 注释、Java 注释类型、Javadoc 工具、注释对性能的影响以及要遵循的最佳实践的所有信息。

1、为什么要写评论？

注释，顾名思义，就是我们在程序之间出于各种原因写的注释。例如，您可以将评论写到 –

• 写出关于变量、方法、类或任何语句的信息或解释。
• 编写可在 Java 文档中使用的文本。
• 隐藏特定时间的程序代码等

给定的代码是 Java 注释的示例，以及如何使用它们。

/**
 * Contains method to greet users by their name and location.
 *
 * @author Lokesh Gupta
 */
public class Main {

	/**
	 * Launches the application
	 *
	 * @param args - Application startup arguments
	 */
	public static void main(String[] args) {
		getMessage("Lokesh", "India");
	}

	/**
	 * Returns welcome message for a customer by customer name and location
	 *
	 * @param name - Name of the visitor
	 * @param region - Location
	 * @return - Welcome message
	 */
	public static String getMessage (String name, String region)
	{
		StringBuilder builder = new StringBuilder();
		builder.append("Hello ");
		builder.append(name);
		builder.append(", Welcome to ");
		builder.append(region);
		builder.append(" !!");
		return builder.toString();
	}
}

2. Java注释的类型

Java 中有 3 种类型的注释。

3.1.单行注释

当注释只能写在一行中时，使用单行注释。这些注释写在 Java 语句之上，以阐明它们在做什么。

//Initialize the counter variable to 0
int counter = 0;

3.2.多行注释

当您需要在源代码中添加超过一行的信息时，使用多行注释。多行注释多用在逻辑复杂，一行写不完的代码块上面。

/*
 * This function returns a variable which shall be used as a counter for any loop.
 * Counter variable is of integer type and should not be reset during execution.
 */
public int getCounter() {
  //
}

3.3.文档注释

当您想要公开信息以供 javadoc 工具获取时，将使用文档注释。这是您在使用自动完成 功能时在编辑器（例如 eclipse）中看到的信息。这些注释位于类、接口和方法定义之上。

文档注释以 /** 开头，以 */ 结尾。您可以在这些评论中使用 javadoc 注释，例如@param 和@return。

/**
  * This function returns a variable which shall be used as a counter for any loop.
  * Counter variable is of integer type and should not be reset during execution.
  *
  * @param seed - initial value of the counter
  * @return counter value
  */
public int getCounter(int seed) {
  //
}

文档注释是编程不可或缺的一部分，不应跳过。

3.评论快捷键

在 Eclipse IDE 中，只需在公共方法或类之前键入“/** [Enter]”，就会自动生成所有必需的@param、@author 和 @return 属性。

eclipse 中的 Java Comment 快捷方式

4.Javadoc实用程序

javadoc 实用程序与 JDK 发行版捆绑在一起。它将它们转换为标准化、格式良好、易于阅读的网页。它根据文档注释生成 API 文档。

4.1.从命令提示符运行 javadoc

首先，确保 javadoc 该实用程序在您的 PATH 中。如果没有，则将 JDK/bin 文件夹添加到 PATH 变量。

要生成 Java 文档，请使用两个参数执行该实用程序。第一个是生成的 Java 文档的位置，第二个是Java 源文件。在我们的例子中，我从 Main.java 所在的位置执行了这个命令。

$ javadoc -d C:/temp Main.java

它生成了这些 Java 文档 HTML 文件。

生成的 Java 文档

4.2.从 Eclipse 运行 javadoc

您也可以从 Eclipse IDE 生成 Java 文档。按照这些简单的步骤-

• 在包资源管理器中，右键点击所需的项目/包。
• 选择Export.../Javadoc 并点击Next。

导出 Java 文档选项

• 默认情况下，将选择整个源代码。验证并更改您的选择。

Eclipse 中的 Java Doc 选项

• 您可以为要生成的可见性级别选择“Private”。这将生成所有可能的 Javadoc，甚至是私有方法。
• 选择“standard doclet”，这是您文档的目标文件夹。
• 点击下一步。
• 输入有意义的文档标题，然后点击完成。

如果您正确执行上述所有步骤，您将生成类似于我们在命令提示符选项中看到的 Java 文档文件。

5. Java 注释对性能的影响

Java 代码中的实现注释仅供人类阅读。 Java 注释是未被编译器编译的语句，因此它们不包含在已编译的字节码（.class 文件）中。

这也是 Java 注释对应用程序性能没有影响的原因。

6. Java 注释最佳实践

遵循这些最佳做法，在您的应用程序源代码中添加适当的注释。

• 不要在源代码中使用不必要的注释。如果您的代码需要的不仅仅是正常的解释，那么可以重构您的代码。
• 保持评论缩进统一和匹配以获得最佳可读性。
• 评论是针对人类的，因此请使用简单的语言进行解释。
• 始终在您的源代码中添加文档注释。

快乐学习！！

标签2： Java Basics Java Basics

地址：https://www.cundage.com/article/java-comments.html