【Java基础知识3】Java注释：单行、多行、文档注释（如何通过 javadoc 命令生成代码文档、如何在IEDA配置自动为所有的类都添加创建者和创建日期）
| 阿里云国内75折 回扣 微信号：monov8 |
| 阿里云国际，腾讯云国际，低至75折。AWS 93折 免费开户实名账号 代冲值 优惠多多 微信号：monov8 飞机：@monov6 |
本文已收录专栏
🌲《Java进阶之路》🌲
目录
如果你学过其他语言的话你会发现Java里面的注释和其他高级语言大多都是一样的下面且看我娓娓道来
🍐01、单行注释
单行注释通常用于解释方法内某单行代码的作用。
public void method() {
int age = 18; // age 用于表示年龄
string name = "张三"//name 表示姓名
}
但如果写在行尾的话其实是不符合阿里巴巴的开发规约的。而且明显的注释或者代码长了就不方便看了。
正确的单行注释如上图中所说在被注释语句上方另起一行使用 // 注释。
public void method() {
// age 用于表示年龄
int age = 18;
}
🍐02、多行注释
多行注释使用的频率其实并不高通常用于解释一段代码、一个方法……的作用。
/*
age 用于表示年纪
name 用于表示姓名
*/
int age = 18;
String name = "张三老师";
以 /* 开始以 */ 结束但不如用多个 // 来得痛快因为 * 和 / 不在一起敲起来麻烦。
当然了这只是单行注释内容不多的话的确方便很多。
// age 用于表示年纪
// name 用于表示姓名
int age = 18;
String name = "沉默王二";
🍐03、文档注释
文档注释可用在三个地方类、字段和方法用来解释它们是干嘛的。
public class Demo {
/**
* 姓名
*/
private int age;
/**
* main 方法作为程序的入口
*
* @param args 参数
*/
public static void main(String[] args) {
}
}
PS在 Intellij IDEA 中按下 /** 后敲下回车键就可以自动添加文档注释的格式*/ 是自动补全的。
接下来我们来看看如何通过 javadoc 命令生成代码文档。
第一步在该类文件上右键找到「Open in Terminal」 可以打开命令行窗口。
第二步执行 javadoc 命令 javadoc Demo.java -encoding utf-8。-encoding utf-8 可以保证中文不发生乱码。
第三步执行 ls -l 命令就可以看到生成代码文档时产生的文件主要是一些可以组成网页的 html、js 和 css 文件。
第四步执行 open index.html 命令可以通过默认的浏览器打开文档注释。
点击「Demo」可以查看到该类更具体的注释文档。
🍐04、文档注释的注意事项
1javadoc 命令只能为 public 和 protected 修饰的字段、方法和类生成文档。
default 和 private 修饰的字段和方法的注释将会被忽略掉。因为我们本来就不希望这些字段和方法暴露给调用者。
如果类不是 public 的话javadoc 会执行失败。
2文档注释中可以嵌入一些 HTML 标记比如说段落标记 <p>超链接标记 <a></a> 等等但不要使用标题标记比如说 <h1>因为 javadoc 会插入自己的标题容易发生冲突。
3文档注释中可以插入一些 @ 注解比如说 @see 引用其他类@version 版本号@param 参数标识符@author 作者标识符@deprecated 已废弃标识符等等。
🍐05、注释规约
1类、字段、方法必须使用文档注释不能使用单行注释和多行注释。因为注释文档在 IDE 编辑窗口中可以悬浮提示提高编码效率。
比如说在使用 String 类的时候鼠标悬停在 String 上时可以得到以下提示。
2所有的抽象方法(包括接口中的方法)必须要用Javadoc注释、除了返回值、参数、 异常说明外还必须指出该方法做什么事情实现什么功能。
3所有的类都必须添加创建者和创建日期。
Intellij IDEA 中可以在「File and Code Templates」中设置。
语法如下所示
/**
* @author 宋宋
* @date ${DATE}
*/
设置好后在新建一个类的时候就可以自动生成了。
/**
* @author 宋宋
* @date 2023/1/14
*/
public class Test {
}
4所有的枚举类型字段必须要有注释说明每个数据项的用途。
5代码修改的同时注释也要进行相应的修改。
🍐06、注释作用
- 第一、注释要能够准确反映设计思想和代码逻辑;
- 第二、注释要能够描述业务含 义使别的程序员能够迅速了解到代码背后的信息。
正常工作或者做项目时一般都需要好些个程序员共同协作不难想象如果你有一个从来不写注释的同事不得把你气死🙈