Java注释
编写程序时,总要为程序添加一些注释,用以说明某段代码的作用,或者某个类的用途、某个方法的功能,以及该方法的参数及返回值的意义。
为什么要编写注释?主要有一下几个方面的考虑:
-永远不要过于相信自己的理解能力。当你思路流畅,进入编程境界时,你可能很快地实现某个功能。但在以后再次阅读这段代码时,可能会不知其所以然,因此为了时刻找回当初编程时的思路,建议编写注释。
-可读性第一,效率第二。如今软件开发愈发复杂,进行一次开发往往不是一个人的工作,需要整个团队协同作战,团队队员之间就需要互相阅读他人的代码,编写注释就是为了能让他人更好更快地理解自己所编写的代码。其次,在后期维护时,仍然可以通过注释来掌握理解程序。从某种角度来说,这同样也提高了团队开发的效率。
-代码即文档!许多人认为,在软件开发中只有像《软件需求规格说明书》等一系列软件开发规范中的word文档才是文档。其实,开发人员编写的源代码也是文档的一部分,我们要把软件里最重要的文档——源代码写规范。
程序注释是源代码的重要组成部分,一份规范的程序源代码中,注释占到了源代码1/3以上。几乎所有的编程语言都会提供添加注释的方法,一般会有单行注释、多行注释。Java语言的注释一共有三种:
-单行注释(// 之后便是单行注释)
-多行注释(/* 在这之间都是注释,可跨多行 */)
-文档注释(/** 在这之间都是文档注释 */)
Java文档注释
可以利用Javadoc工具将Java源代码中的文档注释自动转化成API文档。
javadoc命令的基本用法如下:
javadoc 选项 java源文件|包
上述语法格式中,javadoc支持通配符,比如*.java就表示当前路径下所有java文件。javadoc常用选项有如下几个:
- -d(directory):该选项指定一个路径,用于将生成的API文档放到指定目录下。
- -windowtitle(text):该选项指定一个字符串,用于设置API文档的浏览器窗口标题。
- -doctitle(html-code):该选项指定一个HTML格式的文本,用于指定概述页面的标题。
注意:只有对处于多个包下的源文件来生成API文档时,才有概述页面。 - -header(html-code):该选项指定一个HTML格式的文本,包含每个页面的页眉。
除此之外,javadoc命令还包含了大量其他选项,我们可以通过在命令行窗口执行javadoc -help命令来查看javadoc命令的所有选项。
接下来,看一个具体的例子吧:
首先,编写一个Javadoc类,包含了文档注释。
package com.star.main;
/**
* Description:
* This program is used to test javadoc.
* Program Name:
* Date:
* @author Undergoer
* @version 1.0
*/
public class JavadocTest {
/**
* 成员变量的文档注释
*/
protected String name;
/**
* main方法,程序入口
*/
public static void main(String[] args) {
System.out.println("hello");
}
}
其次,编写一个Test类,这个类包含了对类、构造器、成员变量的文档注释。
package com.star.test;
/**
* Description:
* This program is used to test javadoc.
* Program Name:
* Date:
* @author star
* @version 1.0
*/
public class Test {
/**
* 成员变量文档注释
*/
public int age;
/**
* Test类构造器的文档注释
*/
public Test(){}
}
在命令行窗口执行如下命令,来为刚刚编写的两个java程序生成API文档:
javadoc -d api_doc -windowtitle 测试API -doctitle 学习javadoc -header 我的类 *Test.java
在JavadocTest.java和Test.java所在路径下执行上面命令,可以看到生成API文档的提示信息。
进入此路径,可以看到一个api_doc文件夹,该文件夹下的内容就是刚刚生成的API文档,打开index.html文件,将看到如下图所示的页面。
同样,单击该页面左下角类列表区中的某个类,可以看到该类的详细说明。
除此之外,如果希望javadoc工具生成更详细的文档信息,例如为方法参数、方法返回值等生成详细的说明信息,则可以利用javadoc标记。常用javadoc标记如下:
- @author:指定Java程序的作者
- @version:指定源文件的版本
- @depreated:不推荐使用的方法
- @param:方法的参数说明信息
- @return:方法的返回值说明信息
- @see:“参见”,用于指定交叉参考的内容
- @exception:抛出异常的类型
- @throws:抛出的异常,和@exception同义
最后一点要说明的是,API文档类似于产品的使用说明书,通常只需要介绍那些暴露的、供用户使用的部分,在java类中就是以public或protected修饰的内容,因此javadoc默认只处理public或protected修饰的内容。如果开发者确实希望可以提取private修饰的内容,则可以在命令行使用javadoc工具时增加-private选项。还有,javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的文档注释,忽略其他地方的文档注释。