转载

《JAVA代码规范》（八）类、接口、包和编译单元的标准 (4.1-4.4) ...

4 类、接口、包和编译单元的标准

4.1 类的标准

4.1.1 命名类

标准 Java 约定是使用完全的英文描述符，所有单词的第一个字母要大写，并且单词中大小写混合。类名应是单数形式。

举例：

Customer

Employee

Order

OrderItem

FileStream

String

4.1.2 注释类

以下的信息应写在文档注释中紧靠类的定义的前面：

1. 类的目的。开发者需要了解一个类的一般目的，以判断这个类是否满足他们的需求。养成一个注释与类有关的任何好东西的习惯，例如：它是否是一个模式的一部分，或是使用它时有什么要引起注意的限制。

2. 已知的问题。如果一个类有任何突出的问题，应说明出来，让其他的开发者了解这个类的缺点/难点。此外，还应注明为什么不解决问题的原因。注意：如果问题仅仅针对一个成员方法，那么它应直接与那个成员方法相联系。

3. 类的开发/维护历史。通常要包含一个历史记录表，列出日期、类的作者和修改概要。这样做的目的是让进行维护的程序员了解过去曾对一个类所做的修改，是谁做了什么样的修改。

4. 注释出采用的不变量。不变量是指一套有关实例或类在所有“稳定”时间片内为“真”的声明。“稳定时间片”是指在一个成员函数被对象/类调用之前和立刻调用之后的时间。通过说明一个类的不变量，你让其他的开发者了解应该如何使用一个类。

5. 并行策略。任何采用 Runnable 接口的类应充分说明它的并行策略。对许多程序员来说，并行编程是一个新的而且复杂的题目，所以需要投入一些额外的时间来确保人们能够读懂你的东西。说明你的并行策略以及为什么选取这个策略而不是其它策略这很重要。常用的并行策略包括下面一些内容：同步对象；停滞 (balking) 对象；警戒 (guarded) 对象；版本 (versioned) 对象；同步策略控制器；接收器。

例:

/**

* A class representing a window on the screen.

* For example:

* <pre>

* Window win = new Window(parent);

* win.show();

* </pre>

* @see awt.BaseWindow

* @see awt.Button

* @version 1.2 2004-4-9

* @author wangxie

**/

class Window extends BaseWindow {

...

}

4.2 接口标准

4.2.1 命名接口

在接口名前加前缀“I”。建议在一个接口名的前面附加上字母“I”，结果使名字变为如 ISingleton 或 IRunnable 这样。这种方法有助于将接口名与类和包的名字区分开来。

4.2.2 注释接口

以下的信息应写在文档注释中紧靠接口定义的前面：

Ø 目的。在其他开发者应用一个接口之前，他们需要理解接口封装的概念。换句话说，他们需要了解接口的目的。一个好的检测是否有必要定义一个接口的方法是你是否可以很容易地说明它的目的。如果说明起来有困难，很可能从一开始起就不需要这个接口。在 Java 中接口的概念较新，所以人们对如何正确使用它们还不是很有经验，常常滥用它们。

Ø 它应如何被使用以及如何不被使用。开发者需要了解接口应如何使用以及如何不被使用。

因为成员方法的标识在接口中定义，所以对于每个成员方法的标识应遵循2.7中的注释约定