磨刀不误砍材工 - Java的基础语言要素(注释-生成你自己的API说明文档)

注释是编程工作中一项重要和必不可少的东西。注释的使用并不复杂，其之所以如此重要的原因在于什么？

来看一个概念解释：注释就是对代码的解释和说明。目的是为了让别人和自己很容易看懂。为了让别人一看就知道这段代码是做什么用的。

正确的程序注释一般包括序言性注释和功能性注释。序言性注释的主要内容包括模块的接口、数据的描述和模块的功能。

模块的功能性注释的主要内容包括程序段的功能、语句的功能和数据的状态。

所及，总结来说，书写程序注释最重要的原因在于：增强程序的阅读性。

Java中提供了三种注释方式：

• 单行注释：//这是我的单行注释

• 多行注释：/*

                *这是我的多行注释

                */

• 文档注释：/**

                *

                */

让我们分别通过一些简单的实际运用来了解一下其使用方式：

1.单行注释的应用(单行注释基本也是我们在实际开发中最频繁使用的注释方式)。

我们可以通过对同一个程序，不加注释与加上注释的两种方式来形象的了解注释带来的好处。

不加注释的方式：

package com.tsr.j2seoverstudy.base;

public class JavaExpDemo {
	private boolean flag = true; 

	public void myLoop() {
		int num = 0;             
		while (flag) {
			System.out.println(++num); 
			if (num >= 10) {        
				flag = false;          
			}
		}
	}
}

加上注释的方式：

package com.tsr.j2seoverstudy.base;

public class JavaExpDemo {
	private boolean flag = true; // 这是我定义的循环控制标记

	public void myLoop() {
		int num = 0;         //这是我定义的作为循环控制的数
		while (flag) {
			System.out.println(++num); //循环控制数自增运算并输出自增后的值
			if (num >= 10) {           //当控制数自增到大于等于10时
				flag = false;      //改变循环控制标记，结束循环
			}
		}
	}
}

其程序阅读性的强弱不言而喻。

二、多行注释的应用

Java中多行注释的定义格式为："/* */"的形式。顾名思义，多行注释对应于单行注释，通常就是当我们所需说明的注释较长，这时再使用单行注释就会显的不美观，并且麻烦，因为可能你需要书写多次"//".于是就有了多行注释的用武之地。

同样以我们上面使用单行注释的相同代码来说，如果我们想要对myLoop方法的功能进行注释说明，就可以使用多行注释：

        /*
	 * 自定义的循环控制
	 * 功能说明：
	 * 通过循环标记flag对循环进行控制，当flag值为true时，将继续循环
	 * 同时定义了一个初始值为0的int型变量num,每次循环num会进行自增运算
	 * 当num自增到大于等于0时，循环标记flag的值将被修改为false,从而控制循环结束
	 */
	public void myLoop() {
		int num = 0;             //这是我定义的作为循环控制的数
		while (flag) {
			System.out.println(++num); //循环控制数自增运算并输出自增后的值
			if (num >= 10) {           //当控制数自增到大于等于10时
				flag = false;          //改变循环控制标记，结束循环
			}
		}
	}

三、文档注释的应用

这是我觉得很酷的一种注释方式。为什么这样说呢？

作为一名Java语言的使用者，我们都经常和一个东西打交道：那就是Java的API说明文档。

通过文档注释，我们也可以对自己定义的类，生成一份“说明书”，也就所谓的API说明文档。

来看一下，首先我们定义一个自己的工具类：

package com.tsr.j2seoverstudy.base;

/**
 * 我的数学工具类,提供一系列相应的数学相关运算方法..
 * @author Hql
 * @version 1.0
 */
public class MyMathUtil {
	/**
	 * 比较获取两个数中的最小数
	 * @param num1
	 * @param num2
	 * @return 最小数
	 */
	public static int min(int num1, int num2) {
		return num1 > num2 ? num2 : num1;
	}
	
	/**
	 * 比较获取两个数中的最大数
	 * @param num1
	 * @param num2
	 * @return 最大数
	 */
	public static int max(int num1, int num2) {
		return num1 > num2 ? num1 : num2;
	}
}

我们对我们提供的类以及方法等加上了文档注释。

这时，正如我们可以通过Java提供的javac.exe工具对自己的类进行编译一样，我们可以通过另一样工具javadoc.exe生成自定义的类的说明文档：

运行完毕后，在你指定的对应目录下，你会发现多出了一系列html等文件。

找到一个名为"index.html"的文件，打开，会发现就如同Java的API说明文档一样：

这样的说明文档是大有裨益的，尤其是在如果你向别人提供了一系列的工具类，而别人需要知道使用方法时，这样的说明文档就大有作为了。

简单的总结了Java的各种注释方式，需要我们铭记的是：

要成为一名优秀的程序员，良好的书写代码注释是十分重要的。