Java 注释

学习Java注释的所有知识，包括Java注释的类型、Javadoc工具、注释对性能的影响以及需要遵循的最佳实践。

为什么要写注释？

代码注释，顾名思义，是我们在代码之间写下的注释，编写注释通常有下面几个原因：

帮助理解代码：注释可以说明代码的作用、逻辑、实现方法等，帮助其他人更好地理解代码。
方便维护：对于复杂的代码，注释可以帮助其他人更易于维护和修改代码，以及增加代码的可读性。
提高代码质量：写注释可以迫使程序员思考代码的逻辑，从而提高代码的质量和可靠性。
便于团队协作：团队中的成员可以通过注释更好地协作，避免因为代码不清晰而产生的沟通失败。

可见写代码时写注释是一个非常好的习惯，可以提高代码质量，减少代码维护的成本，同时也可以增加团队协作的效率。

但是请注意不要编写无明显意义的注释。

Java 中的代码注释示例：

/**
 * 输出一个名称和地域的问候信息。
 * 如：Hello 朋友，welcome to 杭州
 *
 * @author Lokesh Gupta
 */
public class WelcomeMain {

	/**
	 * 启动应用程序
	 *
	 * @param args - 应用启动参数
	 */
	public static void main(String[] args) {
		getMessage("朋友", "杭州");
	}

	/**
	 * 返回一个欢迎信息。
	 *
	 * @param name - 访问者名称
	 * @param region - 地域信息
	 * @return - 欢迎信息
	 */
	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();
	}
}

Java 单行注释

在局部代码块中，要为某行代码添加注释时，可以使用单行注释。单行注释写在代码所在行之上，简单明了。

// Default initial capacity. 默认初始容量为 10
int DEFAULT_CAPACITY = 10;

单行注释可以出现在任何地方，但是通常情况下建议写在代码块中，单行注释不会出现在 Java Doc 文档中。

Java 多行注释

当因为逻辑复杂，要添加的注释一行不能完全描述时，可以使用多行注释，Java 中多行注释使用 /* 开头，*/ 结尾。

/*
 *  计算两数之和
 */
int s = x + y;

多行注释也可以出现在任意地方，但是多行注释同样不会出现在 Java Doc 文档中。

Java 文档注释

当你需要通过创建一个 HTML 页面公开源代码中类或方法的注释信息时，可以使用 Java 文档注释。如常见的 JDK API 在线文档，就是通过 Java 文档注释自动生成的。

JavaDoc 需要注释要符合以下规则：

注释以 /** 开头以 */ 结尾，其中的每一行注释都以 * 开头（这一条不是必须的）。
文档注释中，以 @ 开头的内容有特殊含义，如常见的 @author 、@return、@param 等。

下表是常用的具有特殊含义的 JavaDoc 标记。

标签	描述	适用于
`@see`	关联类/方法/网址	Class, method, or variable
`@code`	源代码内容	Class, method, or variable
`@link`	关联类 / 方法	Class, method, or variable
`@author`	作者	Class
`@version`	版本号	Class
`@param`	参数说明	Method
`@return`	返回说明	Method
`@exception`	异常信息	Method
`@deprecated`	声明已过时	Class, method, or variable
`@since`	开始版本	Variable

一个具有 JavaDoc 文档注释的例子：

package com.wdbyte.comment;

/**
 * 输出一个名称和地域的问候信息。
 * 如：Hello 朋友，welcome to 杭州
 * 主要实现方法是 {@link JavaDocDemo#getMessage(String, String)}
 *
 * @author wdbyte
 * @version 1.0
 * @see com.wdbyte.comment.JavaDocDemo#getMessage(String, String) 
 * @since 1.0
 */
public class JavaDocDemo {

    /**
     * 启动应用程序
     *
     * @param args - 应用启动参数
     */
    public static void main(String[] args) {
        System.out.println(getMessage("朋友", "杭州"));
    }

    /**
     * 返回一个欢迎信息。
     * @see <a href="https://docs.oracle.com/en/java/">Java Dcoumentation</a>
     * @param name   - 访问者名称
     * @param region - 地域信息
     * @return - 欢迎信息语句
     */
    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();
    }
}

Javadoc 命令构建文档

JDK 提供了 javadoc 命令工具用于生产 Java doc 文档，使用 -d doc 指定生产的文档目录为 doc 文件夹。

以上面的 Java 文档注释代码为例：

$ javadoc -d doc JavaDocDemo.java
正在加载源文件JavaDocDemo.java...
正在构造 Javadoc 信息...
正在创建目标目录: "doc/"
标准 Doclet 版本 1.8.0_151
正在构建所有程序包和类的树...
正在生成doc/com/wdbyte/comment/JavaDocDemo.html...
正在生成doc/com/wdbyte/comment/package-frame.html...
正在生成doc/com/wdbyte/comment/package-summary.html...
正在生成doc/com/wdbyte/comment/package-tree.html...
正在生成doc/constant-values.html...
正在构建所有程序包和类的索引...
正在生成doc/overview-tree.html...
正在生成doc/index-all.html...
正在生成doc/deprecated-list.html...
正在构建所有类的索引...
正在生成doc/allclasses-frame.html...
正在生成doc/allclasses-noframe.html...
正在生成doc/index.html...
正在生成doc/help-doc.html...

浏览器中浏览生产的 HTML 文档：

IntelliJ IDEA 生成 Java 文档

通过目录 Tools -> Generate JavaDoc 来导出 Java 文档。

Java 注释建议

保持注释的缩进统一，以获得最佳可读性。
注释是给人看的，因此请使用简单的语言来解释（有些同学喜欢使用英文，如果不是面向国际化的开发项目，请考虑下其他英文不好同学的感受）。
注释不应该过于复杂，如果需要特别复杂的注释内容来解释代码，那么可能需要重新思考下当前代码实现是否过于复杂。
保持在代码中添加注释的好习惯，但是不要为了加注释而添加注释。
Java 注释对性能没有任何影响，因为编译后的 class 文件不包含注释信息。

参考：https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

一如既往，文章中代码存放在 Github.com/niumoo/javaNotes.