java基础之 注释

JAVA里有2中注释风格。

一种以 “/*” 开始以 “*/” 结尾，另一种是以 “//” 起头的。

被注释的内容不会被java虚拟机编译，所以这就是为什么用反编译编译源代码没有注释的原因。

举个栗子

package test;

public class JavaDoc {
    /*这是单行注释*/

    /**
     * 这是多行注释
     * 可以写很多行
     */
    
    //这是单行注释，按2次斜杠就可以了

    //这种注释可以只有开头
    //所有也可以写很多行
    
    public static void main(String[] args) {

    }
}

反编译JavaDoc.class后的内容

package test;

public class JavaDoc {
    public JavaDoc() {
    }

    public static void main(String[] args) {
    }
}

扩展

如果你使用 lntelliJ IDEA 进行编码的话，你还可以使用 “//region //endregion“来自已注释代码块，方便阅读源代码哦。可以选中要注释的代码块，然后快捷键 Ctrl+Alt+T ，选择region 即可。

//region 这是把其中的代码折叠起来
public static void main(String[] args) {

}
//endregion

折叠后

这是把其中的代码折叠起来

java文档注释

java文档注释是为了输出代码注释文档，让代码和文档分离，便于查看文档。比如java API 文档，就是java底层开发者的文档注释，每次修改后只要输入文档即可，不用花费时间人力去维护开发的api。

在java文档注释javadoc中可使用嵌入html和“文档标签”，通过javadoc输入的注释文档是一个html文档，所以我们可以在文档注释使用html标签。

如果你想在嵌入的html代码中写行内样式，这是可以滴，为什么？因为我试过了。你可以自己美化你的注释哦，但是这回让你的源注释包含太多样式，不利于阅读，最好还是不要这样搞。

在文档注释中使用嵌入html代码和写html页面一样，大家可自行学习html即可。

在文档“文档标签”的话，需要使用指定的标签和写法，所有的文档标签都是用@ 符号声明，后面记得加空格。

1. @see 引用其类，@see class-name 转化为html标签的 a 标签，链接到其他文档。
2. @author 声明作者。
3. @throws 声明方法可能会跑出的异常，调用者要进行处理。
4. @param 参数说明，@param name desc。以上可文档标签都可写多个，但多个必须是连续的。
5. @return 表示返回值。

举个栗子

package test;
public class JavaDoc {
    /**
     * <p>方法描述：变量自动加一.</p>
     * <p>创建时间：2019-03-31 23:40:54</p>
     * <p>创建作者：李兴武</p>
     *
     * @param i 进行自动加一的数
     * @return 返回加一后的结果
     * @throws RuntimeException 被操作数为0，会抛出异常
     * @author "lixingwu"
     * @see IfElse
     */
    public Integer add(int i) throws RuntimeException {
        if (i == 0) {
            throw new RuntimeException("被操作数不能为0");
        }
        i++;
        return i;
    }
}

输出的JavaDoc.html

扩展

如果您使用的lntelliJ IDEA 进行编码的话，可以使用 Tools -> Generate JavaDoc 来生成文档。

注释规约

根据阿里巴巴java开发手册说明：

1. 【强制】类、类属性、类方法的注释必须是用 /**内容*/ 格式，不得使用//xxx方式;
2. 【强制】所有的抽象类必须有javadoc注释，详细说明其作用；
3. 【强制】所有的javadoc必须有 添加时间 和 创建作者 ；
4. 【强制】方法内的单行注释，必须另起一行，使用 // 注释，多行注释使用 /**/；
5. 【强制】所有的枚举类型必须有注释，说明每项数据的作用；