Java学习第三天之注释

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

一、为什么要添加注释？

　　（1）便于自己理解：有些人可能对此不认同，觉得我自己写的代码难道我自己还能不理解吗，殊不知这是一种错误的想法。一个程序员终其一生要编写多少代码笔者不知，但想必不在少数，再加上人本身的健忘，可能当时能够理解的代码，过后再呈现于眼前真的会不认识。添加注释，便于过后理解，也方便将来进行代码的重构。

　　（2）便于他人理解：我们编写的代码，不仅自己会读，他人也会读，自己写的代码过后拿出来，自己都尚且不理解，更何况是别人。这样的事情在实际工作中是经常遇到的。当你进入一家新的公司，首先便会阅读之前公司一些项目的代码，如果程序的编写人员不添加注释，看起来真的是两眼一抹黑。而且，在一个大型项目中，少不了要分工协作，相互沟通，你得保证你写的代码能够被别人理解。

　　程序注释是源代码的一个重要部分，对于一份规范的程序源代码而言，注释应该占到程序的1/3以上。

二、注释的类型

　　Java语言的注释一共有三种类型：

　　　　单行注释；

　　　　多行注释；

　　　　文档注释。

　　（1）单行注释：就是在程序中注释一行代码。在Java语言中，将双斜线（//）放在要注释的代码之前就可以了。

　　（2）多行注释：指一次性的将程序中的多行代码注释掉。使用“/*”和“*/”将程序中需要注释的内容包含起来。其中，“/*”表示注释开始，“*/”表示注释结束。

　　下面以一段代码展示单行注释与多行注释的用法：

 1 public class HelloWorld {
 2 
 3     /*
 4      * 这是多行注释
 5      * main方法是程序的入口
 6      */
 7     public static void main(String[] args) {
 8 
 9         // 这是单行注释
10         // 下面这段代码表示打印 Hello，World！
11         System.out.println("Hello，World!");
12         // System.out.println("这段代码已被注释，将不会被编译，执行。");
13     }
14 
15 }

　　另外，添加注释也是调试程序的一个重要方法。如果觉得某段代码可能有问题，可以先把这段代码注释起来，让编译器忽略这段代码，再次编译、运行，如果程序可以正常执行，则可以说明错误就是由这段代码引起的，这样就缩小了错误所在的范围，有利于排错；如果依然出现相同的错误，则可以说明错误不是由这段代码引起的，同样也缩小了错误所在的范围。

　　（3）文档注释：如果编写java源代码时添加了合适的文档注释，然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一套系统的API文档。

　　Java提供了大量的基础类，因此Oracle也为这些基础类提供了相应的API文档，用于告诉开发者如何使用这些类，以及这些类里包含的方法。

　　学会使用及阅读JavaAPI文档也是学习Java的重要方式。

　　可以去官网下载Java8的API文档用于学习。

　　　　https://www.oracle.com/technetwork/java/javase/documentation/jdk8-doc-downloads-2133158.html

　　下载好后解压缩，进入到目录的docs/api下，找到index.html，双击即可打开。如下图所示：

　有想了解JavaAPI用法的可以去网上搜索，看不懂英文的可以在网上找中文版的，这里就不详述了。

　　由于文档注释是用于生成API文档的，而API文档主要用于说明类、方法、成员变量的功能。因此，javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其他地方的文档注释。而且javadoc工具默认只处理以public或protected修饰的类、接口、方法成员变量、构造器和内部类之前的注释。

　　文档注释以斜线后紧跟两个星号（/**）开始，以星号后紧跟一个斜线（*/）结束，中间部分全是文档注释，会被提取到API文档中。

　　下面以一段代码示例：

 1 /**
 2  * 这是一个测试生成API文档的类
 3  * @author Administrator
 4  *
 5  */
 6 public class JavadocTest {
 7 
 8     /**
 9      * 这是一个成员变量
10      */
11     protected String name;
12     
13     /**
14      * 这是main方法，是程序的入口
15      * @param args
16      */
17     public static void main(String[] args) {
18 
19         System.out.println("Hello,World!");
20     }
21 
22 }

　　在Java源文件的所在的目录行输入cmd打开命令行窗口，输入javadoc JavadocTest.java，会在当前目录生成许多以.html为后缀的文件，找到index.html双击就可以显示生成的API文档。当然你也可以指定生成目录，可以在命令行输入javadoc指定选项。

　　注释的学习到此结束。