Java规格说明的几点建议

简单介绍一下Java规格说明（specification）书写的几点建议（整理自网络与书籍，在此表示感谢）：

1）规格说明应该是内聚的

       不应当包含许多例子，一大堆变量列表，以及布尔标记，特别是嵌套的if语句，都意味着麻烦。

       只做一件事：对于一个函数它的功能应该是单一的，将不同的功能分离会使它们更简单（容易理解），并且在其他地方更加使用（容易改变）。

 

2）调用结果应该提供有效信息

       对于不同的情况应该提供不同的返回值。例如设计一个处理映射的类（类似于HashMap），对于其get（）方法，若设计在不存在该键值以及该键值对应的值为null时均返回null，便是有歧义的。

       个人理解也就说不应该有歧义。

 

3）规格说明应该足够强

       应当提供足够强的规格说明以满足客户的基本需求。以List的addAll方法为例，做以下规格说明：

       当NullPointerException抛出时，客户无法判断哪个元素导致了这个异常，也就是说，有可能会在添加一部分之后抛出异常，这意味着发生了不合理的变化且用户无法恢复，这对于用户来说是极其棘手的事情。

 

4）规格说明应该足够弱

       同样以例子解释：

                

       该规格说明缺乏重要的细节：文件是读还是写？早已存在还是新建的？

       规格说明过于强，无法保证可以打开这个文件：没有权限或者文件系统出现异常时会怎么样？

       一个更好的表示：试图打开一个文件，成功后该文件有特定的性质。

 

5）规格说明应当使用抽象类型

       针对Java，参数类型建议尽量使用接口而非具体的实现，这会提供给客户和实现者更大的自由。比较简单也就不再举例说明了。