Java 注释

其实已经写了不少代码了，不过写的越多，就越有心慌的感觉，因为时间越久，对之前实现的功能越陌生

注释（comments）是最开始学习 Java 的时候就知道的，不过一直没有很好的使用它，这次完整的学习下注释的语法，以及相应工具的使用

---

参考：

How to Write Doc Comments for the Javadoc Tool

Java 文档注释

---

• 注释分类
• 文档注释
• 文档工具 javadoc
• 注释规范

---

注释分类

注释和代码功能无关，编译器也会忽略注释的内容，它的作用是为了更好的理解代码功能

我们可以使用口语化或者书面化的语句去描述注释的内容，或者利用一些特定的语法来加深理解

Java 提供了 3 种注释

• 单行注释（// ...）
• 块注释（/* ... */）
• 文档注释（/** ... */）

其中的 ... 表示的就是注释内容，可以是多行，如下所示

/**
 * @author zj
 */
public class Time {
    /*
    块注释
     */
    private static final String COMMENT = "块注释";

    /**
     * 获取时间命名字符串，格式：年月日时分秒毫秒
     *
     * @return 字符串，表示年月日时分秒毫秒
     * @see Calendar
     */
    public static String getTimeName() {
        Calendar calendar = Calendar.getInstance();
        int year = calendar.get(Calendar.YEAR);
        int month = calendar.get(Calendar.MONTH);
        int day = calendar.get(Calendar.DAY_OF_MONTH);
        int hour = calendar.get(Calendar.HOUR);
        int minute = calendar.get(Calendar.MINUTE);
        int second = calendar.get(Calendar.SECOND);
        int millisecond = calendar.get(Calendar.MILLISECOND);

        return String.format("%04d%02d%02d%02d%02d%02d%03d", year, month, day, hour, minute, second, millisecond);
    }


    /**
     * 主函数
     *
     * @param args
     */
    public static void main(String[] args) {
        String t = getTimeName(); // 获取时间命名字符串

        // 输出字符串
        System.out.println(t);
    }
}

IDE 快捷键

在 Android Studio 和 Intellij IDEA 中使用如下快捷键进行注释

• Ctrl+/ 表示单行注释
• Ctrl+Shift+/ 表示块注释

---

文档注释

如果仅是为了在代码中添加一些辅助性注释，单行注释和块注释已经能够满足要求

文档注释的一大特点就是其注释内容可以被工具从代码中抽取成单个文档，更加方便查找和理解

除了添加注释内容外，文档注释也提供了一些特定的语法，在文档注释中以 @ 号开头

/**
 * 文档注释说明
 * <p>
 * <a href="http://www.runoob.com/java/java-documentation.html"></a>
 * <a href="http://www.oracle.com/technetwork/java/javase/tech/index-137868.html"></a>
 *
 * @author zj
 * @version 2.0
 */
public class DocCommentDemo {
    /**
     * 名字
     */
    public static final String NAME = "zj";

    /**
     * 取最大值
     *
     * @param a int
     * @param b int
     * @return 最大值
     * @see #getNumMax(int, int)
     * @since 1.0
     * @deprecated
     */
    private int getMax(int a, int b) {
        return a > b ? a : b;
    }

    /**
     * 取最大值，可以查看 {@link Math#max(int, int)}
     *
     * @param a int
     * @param b int
     * @return 最大值
     * @see Math#max(int, int)
     * @since 2.0
     */
    private int getNumMax(int a, int b) {
        return a > b ? a : b;
    }

    /**
     * 获取最小值
     *
     * @param ints int[]
     * @return 最小值
     * @throws NullPointerException      输入参数不能为空
     * @throws InvalidParameterException 输入参数大小不能为0
     * @since 1.0
     */
    private int getNumMin(int[] ints) {
        if (Objects.isNull(ints)) {
            throw new NullPointerException("输入参数数组 ints 不能为空");
        }
        if (ints.length == 0) {
            throw new InvalidParameterException("输入参数数组 ints 大小不能为 0");
        }

        int max = ints[0];
        for (int i = 1; i < ints.length; i++) {
            if (ints[i] < max) {
                max = ints[i];
            }
        }

        return max;
    }

    public static void main(String[] args) {

    }
}

对于类注释而言，需要说明作者，版本号

• 标签 @author 用于说明作者
• 标签 @version 用于说明版本信息

对于函数而言，需要说明参数和返回值，以及抛出的异常

• 标签 @param 用于说明参数
• 标签 @return 用于说明返回值类型

异常标签可以使用 @exception，或者 @throws

较常用的标签还有

• @since 用于说明引入该变化的版本或者时间
• @see 可以链接到另一个主题
• {@link} 作用和 @see 类似，不过这个标签可以使用在注释内部

Note：上面这些是我总结的会经常使用的标签，除了这些标签以外，还可以在文档注释中添加 HTMl 基本标签

参考

javadoc中{@link}与@see的简单使用以及区别

---

文档工具 javadoc

工具 javadoc 在 JDK_PATH/bin 目录下

可以对单个 java 文件进行操作，生成 javadoc 文档

javadoc.exe DocCommentDemo.java -encoding utf-8 -d doc

• 参数 -encoding 用于指定编码，不加会报 GBK 错误
• 参数 -d 用于指定输出路径

在IDE中操作 javadoc

在 Android Studio 和 Intellij IDEA 中都集成了 javadoc 工具，点击菜单栏 Tools -> Generate JavaDoc 即可生成工程文档

---

注释规范

使用 《阿里巴巴Java开发手册》第1.8小节 提供的注释规范

它提供了五条强制性要求，两条推荐和四条参考

强制要求

• 类，类属性和类方法的注释必须使用 Javadoc 规范，使用文档注释
  
  • 用 IDE 编程时，在调用该方法时可以提示方法，参数和返回值的意义（确实有用）
• 所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释，除了返回值，参数，常数说明外，还必须指出该方法做什么事情，实现什么功能
  
  • 比如，对子类的实现要求，或者调用注意事项
• 所有的类都必须添加创建者和创建日期
• 方法内部的单行注释，在被注释语句上方另起一行，使用单行注释（//）。方法内部的多行注释，使用块注释（/**/），注意与代码对齐
  
  • 之前我开发过程中，不太喜欢使用块注释，更喜欢用单行注释代替，只能多练练了
• 所有的枚举类型字段必须要有注释，说明每个数据项的用途

推荐

• 尽可能把话说清楚，英语说不清楚就用中文
• 代码修改后，同时需要修改注释，尤其是参数，返回值，异常，核心逻辑等的修改（这条很重要）

参考

• 谨慎注释掉代码。要在上方详细说明，而不是简单的注释掉。如果无用，则删除
  
  • 个人经验，往往会觉得注释掉的代码可能还会用到，其实永远也不会用了，还不如删掉，不然，程序会越来越臃肿
• 对注释的要求：（1）能够准确反映设计思想和代码逻辑；（2）能够描述业务含义，使其它程序员能够迅速了解代码背后的信息
  
  • 要实现这条的要求需要足够理解代码，同时有良好的书写能力，这个需要多多练习，不过，相对而言，能写比不能写好，没有注释的程序太痛苦了
• 好的命名，代码结构是自解释的，解释力求精简准确，表达到位。避免出现注释的一个极端：过多过滥的注释，因为代码的逻辑一旦修改，修改注释是相当大的负担
• 特殊注释标记，请注明标记人和标记时间。注意及时处理这些标记，通过标记扫描经常处理此类标记
  
  • 代办事宜 （TODO）：（标记人，标记时间，[预计处理时间]） 表示需要实现，还未实现的功能
  • 错误，不能工作 （FIXME）：（标记人，标记时间，[预计处理时间]） 在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正