J2EE企业级开发基础教程(2) - Java编程规范

上一节 J2EE企业级开发基础教程(1) - Hello World 我们介绍了 Java 语言的一些背景，并介绍了 Java 语言环境的配置。

从本节开始，我们将逐步开始介绍 Java 语言的语言特性和语法规则。

在实际工程中，一个团队一定会要求团队成员在写代码的时候，必须遵循统一的规范。只有这样，才能够让整个团队的代码风格统一，才能够让写出的代码有着比较好的可读性。常见的编码规范有： 

1、  良好的注释
2、  良好的标识符命名
3、  良好的缩进
作为一名初学者，一定要在一开始的时候就养成良好的编码习惯。 

1 注释

注释指的是一些描述性的文字.

注释中典型的内容包括：这段代码是如何工作的，这段代码使用了什么算法，这段代码执行的流程如何，等等。

注释不是 Java 代码的一部分，编译时，编译器会把 Java 代码翻译成字节码，而注释则会被编译器自动忽略。因此，代码中有没有注释，都不会影响到代码运行的结果。

但是，注释却是编程中必不可少的内容。有良好注释的代码，能够极大的增强代码的可读性。也就是说，加上注释的代码更容易让人读懂，注释能给程序员带来最大的帮助。

Java 中的注释从语法上来说主要有三种：单行注释、多行注释和 javadoc 注释。

1.1  单行注释

单行注释以“//”开头，直到遇见一个换行符为止。

Eg 1： //This is a comment.
Eg 2： System.out.println(“ ABC”); // This is another comment

1.2 多行注释

多行注释以“/*”开头，以“*/”结尾，在/*和*/之间的所有内容，均作为注释。

Eg 1： /* This is Comment */

多行注释可以跨行，例如：

Eg 2： 
/* This is a example
    Of multi-line comment */

特别要注意的是，多行注释不能嵌套。例如以下程序片段：

/* This is comment
/*can not have inside comment*/
*/

这个程序片段在多行注释中包含了另一个多行注释，会引发一个编译错误。

1.3 javadoc 注释

javadoc 注释，是 Java 中一种比较特殊的注释。这种注释用来生成 api 文档。

程序员在对外发布 Java 代码的时候，还应当对外公布这些代码的用法。

程序员在对外发布 Java 代码的时候，还应当对外公布这些代码的用法。这样，才能让其他的程序员能够更加方便的利用已有的代码。在 Java 中，我们往往使用 api 文档，来向其他程序员介绍代码的组成和用法。例如，Sun 公司发布的 JDK ，包括了一个庞大的类库，为了说明这些类的用法，Sun 公司还提供了相应的 api 文档。

Java1.7 的文档链接如下：

http://docs.oracle.com/javase/7/docs/api/

下图显示了 java.lang.Object 类的 api 文档：

对于我们程序员来说，如何来生成这样的 api 文档呢？很显然，让程序员直接手工编写，是一件非常麻烦的事情。为此，Java 提供了一种相对比较简单的机制。

首先，在代码中，我们可以使用 javadoc 注释。从语法上说，这种注释由“/**”开头，以“*/”结尾，在“/**”和“*/”之间可以有多行文本，并且与多行注释一样，javadoc 注释也不允许嵌套。这是一种特殊的多行注释，可以在代码中描述类、函数等等。然后，在 JDK 安装目录bin中，有一个 javadoc.exe执行程序。这个javadoc命令能够从源文件中获得 javadoc 注释，并根据 javadoc 注释，自动生成 api 文档。

下面我们演示下如何使用，例如我们写下如下代码：

/** 这是对类的注释 */
public class TestJavadoc {
	/**
	 * 这是对主方法的注释 并且有多行
	 */
	public static void main(String args[]) {
		System.out.println("test java doc");
	}
}

上述代码，在类和方法前面，都加上了 javadoc 注释。
然后，进入命令行。在命令行上输入如下命令：

javadoc  –d doc TestJavadoc.java

javadoc 命令能够根据代码中的 javadoc 注释生成文档。“-d  文件夹名”是 javadoc 命令的一个选项，这个选项表示的是，生成的文档要放在后面指定的文件夹下。例如，上面“-d  doc”，就表示生成的 javadoc 文档要放在 doc 目录下。 javadoc 命令最后一个参数，是一个 java源文件的名字，表示要生成哪一个源文件的文档。
使用该命令之后，命令行上运行的结果如下：

然后，在 E:\J2EE企业及开基础教程 目录下，生成了一个 doc 目录，在 doc 目录下，生成了相当多的 html 网页以及一些其他的文件，如下图：

在生成的一系列文件中，可以用浏览器打开 index.html 网页，显示如下： 

javadoc 命令自动为我们生成了上图显示的文档。在文档中，“这是对类的注释”，以及“这是对主方法的注释  并且有多行”，这些内容都来源于我们在TestJavadoc.java 中写的
javadoc 注释。

2 编码规范

上面我们介绍了注释的语法，下面，我们对“标识符和命名”以及“缩进”做进一步的介绍。

2.1 标识符命名

标识符，指的是程序员为程序组件起的名字。起名字是一门艺术，这一点对标识符也一样。良好的标识符命名风格和习惯，能够大大增加代码的可读性。

我们首先来介绍一下 Java 中标识符的分类。标识符为程序组件的名字，而所有的 Java程序组件基本分为 5 大类：包、类、变量、函数、常量。首先我们介绍一下 Java 标识符的命名规则。
在 Java 中，关于标识符命名有三条规则。如果我们定义的标识符违背了语法规则，编译时将不能通过。
标识符命名的规则如下：

1 Java 标识符由字母、数字、下划线(_)、货币符号($)组成，其中数字不能开头
要注意的是，所谓“字母”，从技术上说，是一个 unicode 字符，包括中文字符。换句话说， Java 标识符能够使用中文。

例如，你可以写一个类叫做“学生” ，写一个变量叫做“成绩”等等，Java 程序照样认得。但是在实际编程中，为了避免一些不必要的麻烦，所有 Java程序员都会使用英文字母起名。对大部分程序员来说，代码里面出现中文总觉得怪怪的。

2 Java 标识符区分大小写

3 不能与 Java 关键字重名

注意，Java 中有两个单词：goto / const，他们在 Java 中没有特殊的含义，但是由于这两个单词在其他语言中（例如 C 语言）有特殊含义，为了避免其他语言的程序员学习 Java 时产生混淆和误会，Java 语言不允许程序员使用这两个单词。也就是说，虽然在 Java 语言中。goto 和 const 这两个单词没有特殊含义，但是程序员在给程序组件起名字时，依然不能用这两个单词。 

除了语法规则之外，还有一些标识符命名方面的习惯。 违反了这些习惯的标识符可能是符合语法，从而能够编译通过的。但使用了这样的标识符，会被认为是不良好，不规范的。
在 Java 语言中，标识符命名应该注意两大习惯：
1 望文生义
这指的是说，标识符的名字应当起的有意义， 最好能通过名字，让人一眼就能看出标识符的作用。例如，变量 totalScore 肯定是用来统计总分，函数 addStudent 肯定是用来增加一个学生。这样的名字是比较好的名字。 它们很容易让人理解这个标识符的意义，从而提高程序的可读性。
2 大小写规范
相比上一条规范，这一条显得非常教条。 Java 语言中，对于不同的程序组件，有着不同的大小写规范。罗列一下：

包名：全小写。例如 java.lang
类名：每个单词首字母大写。例如 HelloWorld
变量/函数名：首单词小写，后面每个单词首字母大写。例如 helloWorld
常量名：全大写，单词之间用下划线分隔。例如 HELLO_WORLD

我们可以参考 Java SE 类库中的命名方式，会发现所有的标识符都符合上述两个习惯。这无疑是 Java 世界中约定俗成的，所有程序员都恪守的准则。如果你是一个 Java 初学者，也请从一开始就养成良好的标识符命名习惯，千万不要轻视它们！

2.2 缩进

缩进，指的是在写代码的时候，在某些行的行首，会留出一些空白字符。良好、规范的缩进能够极大的提高代码的清晰程度，让可读性大大增加。
例如，下面的代码，有着混乱的换行和缩进。

import book.corejava..HelloWorld; class BadCode
{public static void main(String
args[]){System.out.println("welcome")
;HelloWorld
hw;}}

然而神奇的是，这一段代码能够编译通过。但是，这样的代码，可读性简直差到了极致！不仔细看几遍是很难读懂这段代码的。
而实际上，对上面的代码简单调整一下换行和缩进，马上就焕然一新：

import book.corejava.HelloWorld; 
class GoodCode{
	public static void main(String args[]){
		System.out.println("welcome");
		HelloWorld hw;
	}
}

对于缩进的使用，应当注意下面两条：
第一，  对于每一个代码块，其内容都应当缩进。例如， class 顶格写，而 class 的内容，相对于 class 都应当有缩进。类似的，主方法有一级缩进；而主方法的所有内容，都应当在主方法的基础上，再缩进一级。
第二，  缩进应当统一。也就是说，每一级缩进的长度应当一致。比较推荐的缩进长度是四个空格或者一个制表符（也就是按键盘上的 tab 键所产生的空白）。

3 忠告

本节主要讲述了Java语言注释，编码规范， 作为一名初学者，一定要在一开始的时候就养成良好的编码习惯， 千万不要轻视它们！！！

本文原文链接，http://blog.csdn.net/herry16354/article/details/44046177