转载

《JAVA代码规范》（十）成员函数和方法标准 (6.1-6.6)

6 成员函数和方法标准

6.1 命名函数和成员方法

成员函数的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。成员函数名称的第一个单词常常采用一个有强烈动作色彩的动词。

例：

openAccount()

printMailingLabel()

save()

delete()

这种约定常常使人一看到成员函数的名称就能判断它的功能。虽然这种约定要使开发者多做一些输入的工作，因为函数名常常较长，但是回报是提高代码的可理解性。

6.2 命名存取成员函数和方法

获取成员函数应在名字中加上 get + 字段名，除非字段表示的是一个布尔值（“真”或者“假”），这时获取函数名中应加上 is + 字段名。无论何种字段类型，设置成员函数应在名字中加上 set + 字段名。注意字段名始终采用大小写混合，所有单词的第一个字母要大写。命名约定在 JDK 中被始终使用，在 beans development 中也必须使用。

Examples:

字段

类型

获取函数名

设置函数名

firstName

字符串

getFirstName()

setFirstName()

address

地址

对象

getAddress()

setAddress()

persistent

布尔值

isPersistent()

setPersistent()

customerNo

整型

getCustomerNo()

setCustomerNo()

orderItems

OrderItem

的对象数组

getOrderItems()

setOrderItems()

6.3 命名构造函数

构造函数是在一个对象初次生成时，完成所有必需的初始化的成员函数。构造函数与它所属类的名字总是相同的。例如，类 Customer 的构造函数是 Customer()。注意大小写一致。

例：

Customer()

SavingsAccount()

PersistenceBroker()

这个命名约定由 Sun 公司设定，必须严格遵守。

6.4 成员函数和方法的可见性

良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有 (public)，就定义为保护 (protected)；没必要保护 (protected)，就定义为私有 (private)。

可见性	说明	正确用法
public	公有成员函数可被任何其它对象和类的成员函数调用。	当该成员函数必须被该函数所在的层次结构之外的其他对象和类在访问时。
protected	被保护的成员函数可被它所在的类或该类的子类的任何成员函数调用。	当该成员函数提供的行为被它所在类的层次结构内部而非外部需要时。
private	私有成员函数只可以被该类所在的其它成员函数调用，该类的子类不可以调用。	当该成员函数所提供的行为明确针对定义它的类时。私有成员函数常常是重新分配要素的结果。重新分配要素又叫“重组”，指类内其它成员函数封装某一个特定行为的做法。

6.5 成员函数和方法参数标准

6.5.1 命名参数

参数命名遵循与局部变量命名完全一样的约定。

6.5.2 注释参数

成员函数的参数在采用 javadoc @param 标识的头文件中注释。应说明：

Ø 参数用来做什么。需要注释出参数用来做什么，以便其他开发者了解使用参数的上下文。

Ø 任何约束或前提条件。 如果一个参数的值域不能被成员函数接收，则应让调用者知道。可能一个成员函数只接收正数，或者字符数小于五的字符串。

Ø 示例。如果应传递什么样的参数不明显，那么应该在注释中给出一个或多个例子。

Ø 采用参数类型接口。若合适的话，不要只说明参数类型属于哪一类，如 Object，而应说明属于哪个接口，例如 Runnable。这样的好处是，这种有赖于环境的方法更具体（Runnable 比 Object 更具体），或者在支持多态性（不坚持一个参数是一个类的层次结构中某个类的实例，而说明它支持一个特定的接口，这意味着它只用多态地适应你的需要即可）上是一个更好的方法。

6.6 注释成员函数和方法

如何注释一个成员函数和方法常常成为判断函数和方法是否可被理解，进而可维护和可扩展的决定性因素。注释在源代码的前面，用来记录所有重要的有助于理解函数的信息。这些信息包含但不仅仅局限于以下内容：

Ø 成员函数做什么以及它为什么做这个。通过给一个成员函数加注释，让别人更加容易判断他们是否可以复用代码。注释出函数为什么做这个可以让其他人更容易将你的代码放到程序的上下文中去。也使其他人更容易判断是否应该对你的某一段代码加以修改（有可能他要做的修改与你最初为什么要写这一段代码是相互冲突的）。

Ø 哪些参数必须传递给一个成员函数。还必须说明，如果带参数，那么什么样的参数必须传给成员函数，以及成员函数将怎样使用它们。这个信息使其他程序员了解应将怎样的信息传递给一个成员函数。在 (第 2.7.4 节“快速浏览 javadoc”) 中讨论的 javadoc @param 标识便用于该目的。

Ø 成员函数返回什么。如果成员函数有返回值，则应注释出来，这样可以使其他程序员正确地使用返回值/对象。在 (第 2.7.4节“快速浏览 javadoc”) 里讨论的 javadoc @return 标识便用于此目的。

Ø 已知的问题。成员函数中的任何突出的问题都应说明，以便让其他程序开发者了解该成员函数的弱点和难点。如果在一个类的多个成员函数中都存在着同样的问题，那么这个问题应该写在类的说明里。

Ø 任何由某个成员函数抛出的异常。应说明成员函数抛出的所有异常，以便使其他程序员明白他们的代码应该捕获些什么。在 (第 2.7.4节“快速浏览 javadoc”) 中讨论的 javadoc @exception 标识便用于此目的。

Ø 可见性决策。如果你觉得你对于一个成员函数可见性的选择会遭到别人的质疑，例如可能你将一个成员函数设为公共的，但是却没有任何对象调用该成员函数，那么应说明你的决定。这将帮助其他开发者了解你的想法，使他们不必浪费时间操心考虑你为什么要选择一种有疑问的东西。

Ø 成员函数是如何改变对象的。若一个成员函数修改了一个对象，例如一个银行帐户的成员函数 withdraw() 修改了帐户余额，那么就需要说明。这种信息必须给出，使其他 Java 程序员能准确地知道一个成员函数调用将如何影响目标对象。

Ø 如何在适当情况下调用成员函数的例子。最简单的确定一段代码如何工作的方法是看一个例子。考虑包含一到两个如何调用成员函数的例子。

Ø 可用的前提条件和后置条件。前提条件是指一个成员函数可正确运行的限制条件；后置条件是指一个成员函数执行完以后的属性或声明。前提条件和后置条件以多种方式说明了在编写成员函数过程中所做的假设，精确定义了一个成员函数的应用范围。

Ø 所有并行事件。对众多程序开发者来说，并行性是一个新而复杂的概念；对有经验的并行性程序开发者来说，并行性也是一个老但却复杂的课题。最终结果是，如果应用了 Java 的并行编程特性，那么应在程序中详细地将其注释出来。当一个类既包含了同步也包含了非同步的成员函数时，必须注释出成员函数依赖的执行上下文，尤其是当函数可被无约束访问时。这样可以让其他开发者安全地使用你的成员函数。当一个采用了 Runnable 接口的类的设置函数（即可更新一个字段的成员函数）没有同步时，应说明这样做的理由。最后，如果覆盖或重载一个成员函数，并且修改了它的同步性时，也应说明理由。

在注释中增加如下标签。

l @param paramName description.

l @return description of return value

l @exception exceptionName description

l @see string

l @see URL

l @see classname#methodname

例:

/**

* Insert element at front of the sequence

* @param element the element to add

* @return condition: