1.4　程序文档风格和注释

写出正确的、可运行的Java程序固然重要，但是，编写出易于阅读和可维护的程序同样重要。一般来说，在软件的生命周期中，80%的花费耗费在维护上，因此在软件的生命周期中，很可能由其他人来维护代码。无论谁拿到你的代码，都希望它是清晰的、易读的代码。

采用统一的编码规范是使代码易于阅读的方法之一。编码规范包括文件名、文件的组织、缩进、注释、声明、语句、空格以及命名规范等。

1.4.1　一致的缩进和空白

保持一致的缩进会使程序更加清晰、易读、易于调试和维护。即使将程序的所有语句都写在一行中，程序也可以编译和运行，但适当的缩进可使人们更容易读懂和维护代码。缩进用于描述程序中各部分或语句之间的结构关系。如类体中代码应缩进，方法体中的语句也应有缩进。Java规范建议的缩进为4个字符，有的学者也建议缩进2个字符，这可根据个人的习惯决定，但只要一致即可。

二元操作符的两边也应该各加一个空格，如下面语句所示：

1.4.2　块的风格

代码块是由大括号围起来的一组语句，如类体、方法体、初始化块等。代码块的大括号有两种写法，一是行末格式，即左大括号写在上一行的末尾，右大括号写在下一行，如程序1.1所示；另一种格式称为次行格式，即将左大括号单独写在下一行，右大括号与左大括号垂直对齐，如下代码所示：

这两种格式没有好坏之分，但Java的文档规范推荐使用行末格式，这样使代码更紧凑，且占据较少空间。本书与Java API源代码保持一致，采用行末格式。

1.4.3　Java程序注释

像其他大多数编程语言一样，Java允许在源程序中加入注释。注释是对程序功能的解释或说明，是为阅读和理解程序的功能提供方便。所有注释的内容都被编译器忽略。

Java源程序支持三种类型的注释。

（1）单行注释，以双斜杠（//）开头，在该行的末尾结束。

例如：

（2）多行注释，以“/*”开始，以“*/”结束的一行或多行文字。

例如：

（3）文档注释，以“/**”开始，以“*/”结束的多行。文档注释是Java特有的，主要用来生成类定义的API文档。具体使用JDK的javadoc命令将文档注释提取到一个HTML文件中。关于文档注释的更详细信息，请参阅有关文献。