Java 中的注释

亦凉 2021-09-27 08:36 285阅读 0赞

##  编写注释的原因 ##

编写程序时总需要为程序添加一些注释，用以说明某段代码的作用，或者说明某个类的用途、某个方法的功能，以及该方法的参数和返回值的数据类型及意义等。

编写注释的原因及意义如下

1、为了更好的阅读自己编写的代码，建议添加这注释。自己写的代码，可能过一段时间回顾的时候，就变得不熟悉。这个时候，注释就起到了很好的帮助作用。

2、可读性第一，效率第二。一个软件一般都是一个团队协同作战开发出来的。因此，一个人写的代码，需要被整个团队的其他人所理解。

3、代码即文档。程序源代码是程序文档的重要组成部分。

# #

## 注释的语法规则 ##

编写Java中的注释不会出现在可执行程序中。因此，可以在源程序中根据需要添加任意多的注释，而不必担心可执行代码会膨胀。在 Java 中，有三种书写注释的方式。

1、单行注释

2、多行注释

3、文档注释

下面分别详细的介绍这三种注释。

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

// 作者：louis.
    // 日期：08/26.
    
    // 类名：FirstSample.
    // 作用：一个简单的 Java 应用程序.
    public class FirstSample
    {
    	// main 方法，Java 应用程序的入口
    	public static void main(String[] args)
    	{
    		// 向控制台输出语句 "Hei,Hei".
    		System.out.println("Hei,Hei");
    		// 下面这句代码被注释掉了，不会执行！
    		// System.out.println("Hei,Hei! Again.");
    	}
    }// FirstSample 类的所有成分都应该定义在 FirstSample 类的一对大括号（"{}"）内.

多行注释：注释内容放到 "/\*" 和 "\*/"之间。也即是，注释从 "/\*" 开始，到 "\*/" 结束。

/* 作用：louis. */
    /* 日期：08/26. */
    
    /* 类名：FirstSample.
       作用：一个简单的 Java 应用程序. */
    public class FirstSample
    {
    	/* 可以注释一行内容 */
    	/* main 方法，Java 应用程序的入口 */
    	public static void main(String[] args)
    	{
    		
    		System.out.println("Hei,Hei");
    		/* 也可以注释多行内容 */
    		/*
    		System.out.println("不知道说什么了，举什么例子好呢？");
    		System.out.println("Hei,Hei! Again.");
    	        */
    	}
    }

tips：需要注意的是，多行注释 "/\*"、"\*/" 不可以嵌套。

如果多行注释进行了嵌套，会发生什么呢？

public class FirstSample
    {
    	public static void main(String[] args)
    	{
    		
    		System.out.println("Hei,Hei");
    		// 下面演示多行注释进行嵌套
    		/*
    		System.out.println("不知道说什么了，举什么例子好呢？");
    		/* System.out.println("Hei,Hei! Again."); */
    	        */
    	}
    }

编译这段代码后，编译结果如下，

![70][]

编译错误，因为在多行注释 "/\*"、"\*/" 中嵌入了多行注释，那么第一个多行注释的 "/\*" 就会和第二个多行注释的 "\*/" 相匹配。第二个多行注释的 "/\*" 被当做了注释的一部分，第一个多行注释的 "\*/" 变成了多余的符号，所以第11行代码出错。

文档注释：Java 语言提供了专门用于生成文档的注释。

文档注释是以 "/\*\*" 开始，以 "\*/"结束的。

/**
     * This is a simple class.
     * @author louis
     * @version 1.0
     */
    public class FirstSample
    {
    	/**
    	 * main function,the entrance of Java Application.
    	 * @param args command line arguments.
    	 */
    	public static void main(String[] args)
    	{
    		System.out.println("Hei,Hei");
    	}
    }

本文的代码是存放在 "louis" 文件夹下的，下面是生成文档之前的文件夹信息，已有一个 Java 源程序文件。

![70 1][]

下面使用 JDK 中的 javadoc 命令，来生成 Java 的 API 文档，命令是：

javadoc

![70 2][]

本文这里使用简单的 javadoc 命令，

javadoc -d docs FirstSample.java

在 "FirstSample.java" 所在文件夹中新建一个文件夹 "docs"，存放生成的文档文件。

![70 3][]

如果运行后，没有错误，那么就生成了正确的文档。

打开 "FirstSample.java" 所在的文件夹 "louis"，在它里面有一个 "docs" 的新文件夹生成，

![70 4][]

可以打开这个文件夹，看看里面都有什么文件。

![70 5][]

我们只关心这个名为 "index.html" 的文件，使用浏览器打开它。

可以看到如下的信息：

![70 6][]

这里，注释的信息比较少，所以文档的信息也比较少。

可以将这个 html 文档大致分为5个部分。

第一部分：类的导航部分；

第二部分：快速切换浏览信息的部分；

第三部分：当前类的信息大致介绍；

第四部分：当前类的方法的概要介绍；

第五部分：当前类的方法的详细介绍。

读者可以自己多添加注释尝试一下。

Over！

[70]: /images/20210923/80dcf16aa2c249f7af6878b57d3d7061.png
[70 1]: /images/20210923/efa71ac309814cf7bcd9826bb0b63d6d.png
[70 2]: /images/20210923/e2697ce78c0a41cbbe3e04a9d3801613.png
[70 3]: /images/20210923/d6316887c50647e081a1772bfc3dec58.png
[70 4]: /images/20210923/9b6f8c8f4dcf46e6b0e3f99dac7675cc.png
[70 5]: /images/20210923/83ba871fae604b39ae4d71d9223c3269.png
[70 6]: /images/20210923/fa7875ab7e5147b39e33f75f208219ac.png