java基础之 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. 【强制】所有的枚举类型必须有注释，说明每项数据的作用；