1、你的第一个Java程序
在每个程序文件的开头,必须声明import语句,以便引入在文件代码中需要用到的额外类。类的名字必须和文件名相同。public关键字意指这是一个可由外部调用的方法。main()方法的参数时一个String对象的数组。
在程序中并未用到args,但是Java编译器要求必须这样做,因为args要用来存储命令行参数。
一、编译和运行
安装JDK开发环境。
2、注释和嵌入式文档
Java里有两种注释风格。一种是传统的C语言风格的注释----C++也继承了这种风格。此种注释以 “ /* ”开始,随后是注释内容,并可跨越多行,最后以 “ */ ” 结束。进行编译时,/* 和 */ 之间的所有东西都会被忽略。第二种风格的注释也源于C++。这种注释是“单行注释”,以一个 “ // ” 起头,直到句末。
一、注释文档
javadoc 是用于提取注释的工具,是jdk安装的一部分。它采用了Java编译器的某些技术,查找程序内的特殊注释标签。它不仅解析由这些标签标记的信息,也将毗邻注释的类名或方法名抽取出来。
javadoc输出的是一个HTML文件,可以用web浏览器查看。这样,该工具就使得我们只需创建和维护单一的源文件,并能自动生成有用的文档。有了javadoc,就有了创建文档的简明直观的标准;我们可以期望、甚至要求所有的Java类库都提供相关的文档。
此外,如果想对javadoc处理过的信息执行特殊的操作,那么可以通过编写你自己的被称为“doclets”的javadoc处理器来实现。
二、语法
所有javadoc命令都只能在“/**”注释中出现,和通常一样,注释结束于“*/”。
使用Javadoc的方式主要有两种:嵌入HTML,或使用“文档标签”。独立文档标签是一些以“@”字符开头的命令,且要置于注释行的最前面(但是不算前导“*”之后的最前面)。而“行内文档标签”则可以出现在javadoc注释中的任何地方,它们也是以“@”字符开头,但要括在花括号内。
共有三种类型的注释文档,分别对应于注释位置后面的三种元素:
类、域和方法。也就是说,类注释正好位于类定义之前;域注释正好位于域定义之前;而方法注释也正好位于方法定义的前面。
注意,javadoc只能为public(公共)和protected(受保护)成员进行文档注释。private(私有)和包内可访问成员的注释会被忽略掉,所以输出结果中看不到它们(不过可以用-private进行标记,以便把private成员的注释也包括在内)。
三、嵌入式HTML
javadoc通过生成的HTML文档传送HTML命令,这使你能够充分利用HTML。当然,其主要目的还是为了对代码进行格式化,例如:
//:object/Documentation2.java
/**
* <pre>
*System.out.println(new Date());
*</pre>
*/
///:~
也可以像在其他Web文档中那样运用HTML,对普通文本按照你自己所描述的进行格式化:
//:object/Documentation3.java
/**
*You can <em>even</em> insert a list:
*<ol>
*<li>Item one
*<li>Item two
*<li>Item three
*</ol>
*/
///:~
注意,在文档注释中,位于每一行开头的星号和前导空格都会被Javadoc丢弃。javadoc会对所有内容重新格式化,使其与标准的文档外观一致。
不要在嵌入式HTML中使用标题标签,例如<h1>或<hr>,因为javadoc会插入自己的标题,而你的标题可能同它们发生冲突。
所有类型的注释文档------类,域和方法------都支持嵌入式HTML。
四、一些标签示例
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
@see标签允许用户引用其他类的文档。javadoc会在其生成的HTML文件中,通过@see标签链接到其他文档。格式如下:@see classname@see fully-qualified-classname@see fully-qualified-classname#method-name上述每种格式都会在生成的文档中加入一个具有超链接的“See Also”(参见)条目。但是javadoc不会检查你所提供的超链接是否有效。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签与@see及其相似,只是它用于行内,并且是用“label”作为超链接文本而不用“See Also”。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签产生到文档根目录的相对路径,用于文档树页面的显式超链接。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签的格式如下:
@version version-information
其中,”version-information“可以是任何你认为适合包含在版本说明中的重要信息。如果javadoc命令使用了”-version“标记,那么就 从生成的HTML文档中特别提取出版本信息。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签的格式如下:
@author author-information
其中,
author-information一看便知是你的姓名,但是也可以包括电子邮件地址或者其他任何适宜的信息。如果javadoc命令行使用 了-author标记,那么就从生成的HTML 文档中特别提取作者信息。
可以使用多个标签,以便列出所有作者,但是它们必须连续放置。全部作者信息会合并到同一段落,置于生成的HTML中。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签允许你指定程序代码最早使用的版本,可以在HTML Java文档中看到它被用来指定所用的JDK版本的情况。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签用于方法文档中,形式如下:
@param parameter-name description
其中,parameter-name是方法的参数列表中的标识符,description是可延续数行的文本,终止于新的文档标签出现之前。可以使
用任意多个这种标签,大约每个参数都有一个这样的标签。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签用于方法文档,格式如下:
@return description
其中,” description“用来描述返回值的含义,可以延续数行。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
异常是由于某个方法调用失败而”抛出“的对象。尽管在调用一个方法时,只出现一个异常对象,但是某个特殊方法可能会产生任意 多个不同类型的异常,所有这些异常都需要进行说明。所以,异常标签的格式如下:
@throws fully-qualified-class-name description
其中fully-qualified-class-name给出一个异常类的无歧义的名字,而该异常类在别处定义。description(同样可以延续数行)告诉你
为什么此特殊类型的异常会在方法调用中出现。
![](https://i-blog.csdnimg.cn/blog_migrate/4894808aa685ba8e745fd82e6a5271e4.png)
该标签用于指出一些旧特性已由改进的新特性所取代,建议用户不要再使用这些旧特性,因为在不久的将来它们很可能会被删除。如果使用一个标记为@deprecated的方法,则会引起编译器发布警告。
五、文档示例
//:object/HelloDate.java
import java.util.*;
/**The first Thinking in java example program.
*Displays a string and today's date.
*@author Bruce Eckel
*@author
www.MindView.net
*@version 4.0
*/
public class HelloDate{
/**Entrv point to class & application.
*@param args array of string arguments
*@throws exceptions No exceptions thrown
*/
public static void main(String [] args){
System.out.println("Hello, it's:");
System.out.println(new Date());
}
}
///:~
第一行采用我自己独特的方法,用一个”:”作为特殊记号说明这是包含源文件名的注释行。该行包含文件的路径信息(此时,object代表本章),随后是文件名。最后一行也是一行注释,这个“///:~”标志源代码清单的结束。自此,再通过编译器和执行检查后,文档就可以自动更新成本书的文本。
3、编码风格
在“Java编程语言编码约定”中,代码风格是这样规定的:
类名的首字母要大写;如果类名由几个单词构成,那么把它们并在一起(也就是说,不要用下划线来分隔名字),其中每个内部单词的首字母都采用大写形式。这种风格有时称作“驼峰风格”。几乎其他所有内容----方法、字段(成员变量)以及对象引用名称等,公认的风格与类的风格一样,只是标识符的第一个字母采用小写。