【JavaSe】基础篇(七) Java中的三种注释

JavaSe·基础篇(七) Java中的三种注释

---

注释

就是对代码的解释和说明。其目的是让人们能够更加轻松地了解代码。为代码添加注释，是十分必须要的，它不影响程序的编译和运行。

Java中的三种注释

• 单行注释

  // 这是单行注释
  

• 多行注释

  /*
  	这是多行注释
  */
  

• 文档注释：

  /**
   * 这是多行注释
   */
  

【单行注释】

是最常用的注释方式，其注释内容从 "//"开始到本行末尾。

// 作者：小超哥
// 内容：演示单行注释
public class SingleLineComments{
	// main 方法，Java 应用程序的入口
	public static void main(String[] args){
		// 向控制台输出语句 "此行会被输出".
		System.out.println("此行会被输出");
		// 下面这句代码被注释掉了，代码将不会得到执行
		// System.out.println("此行不会被输出，因为被注释掉了");
	}
}

【多行注释】

注释内容放到 "/" 和 "/"之间。也即是，注释从 “/" 开始，到 "/” 结束。

/**
 * @author 小超哥
 * @version 1.0
 * 该类演示文档注释的作用
 */
public class DocComments{
	/**
	 * 无参构造方法
	 */
	public DocComments(){}
	/**
	 * max计算两个值是否相等
	 * @param a 第一个值
	 * @param b 第二个值
	 * @return 返回两值相加
	 */
	public static int max(int a, int b){
		return a + b;
	}
}

注意：多行注释不能嵌套使用！

【文档注释】

Java 语言提供了专门用于生成文档的注释，文档注释是以 “/**” 开始，以 "*/"结束的。

/**
 * @author 小超哥
 * @version 1.0
 */
public class DocComments{
	/**
	 * max计算两个值是否相等
	 * @param a 第一个值
	 * @param b 第二个值
	 */
	public static void max(int a, int b){
		System.out.println(a + b);
	}
}

下面我们就简单学习下使用javadoc命令来生成JAVA API文档：

使用JDK提供的命令：
javadoc -d docs DocComments.java

此时与类的同路径下生成了一个docs文件夹，里面生成了很多文件，我们打开index.html

打开后我们发现这个界面似曾相识，他和我们平时看的JDK API文档是一模一样的，只是我们注释的信息比较少，所以文档的信息也比较少。其实我们所使用的JDK API文档也是通过javadoc命令来生成的

常见javadoc注释标签语法

标签	作用域	说明
@author	类	标明开发该类模块的作者
@version	类	标明该类模块的版本
@see	类，属性，方法	参考转向（相关主题）
@param	方法	对方法中某参数的说明
@return	方法	对方法返回值的说明
@exception	方法	方法抛出的异常类型
@throws	方法	方法抛出的异常类型说明
@deprecated	方法	说明不建议使用该方法

学习阿里的注释规范

1. 【强制】类、类属性、类方法的注释必须使用javadoc规范，使用/*内容/
2. 【强制】所有抽象方法必须要用javadoc注释，除了返回值、参数、异常说明外，还必须支持该方法做什么事情，实现什么功能
3. 【强制】所有的类都必须添加创建者和创建日期
4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用 // 注释。方法内部多行注释使用 /* */ 注释，注意与代码对齐
5. 【强制】所有枚举类型字段必须要有注释，说明每个数据项的用途