如何在 Java 中编写注释

位置:首页>文章>详情   分类:Java教程   阅读(307)   2023-06-26 07:54:18

了解有关 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 评论快捷方式

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 文档 - 2

生成的 Java 文档

4.2.从 Eclipse 运行 javadoc

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

  • 包资源管理器中,右键点击所需的项目/包。
  • 选择Export.../Javadoc 并点击Next
导出 Java 文档选项

导出 Java 文档选项

  • 默认情况下,将选择整个源代码。验证并更改您的选择。
Eclipse 中的 Java Doc 选项

Eclipse 中的 Java Doc 选项

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

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

5. Java 注释对性能的影响

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

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

6. Java 注释最佳实践

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

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

快乐学习!!

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