Question

我有一个关于在javadocs中记录逻辑的问题。例如，我在界面中有以下方法签名：

public int getTotalAssociationsAsParent(Long id, Long type);

该方法返回给定ID为父级且关联类型为“type”的关联。 ID是必需的，但如果传入的类型为NULL，那么我将返回ID为父级的所有关联。

我的问题是这种逻辑应该记录在哪里？我犹豫是否将它放在接口的javadoc中，因为这种约束所有实现类都遵循该逻辑。也许在将来，如果type为NULL，我将会有一个抛出IllegalArgumentException的Impl类。

但是，如果我将它放在Impl类的非javadoc中，那么此方法的使用者将不知道该方法如何使用NULL类型。

Answer 1

您描述的是该方法的接口契约，因此它确实属于Javadoc。接口的客户端需要知道此接口实现的确切契约。如果派生类以不同方式实现该方法，则会有效地破坏契约，从而破坏Liskov Substitution Principle。

但是，如果您觉得这个方法的不同实现确实存在，那么您有一些选择：

重新考虑你的设计 - 也许这些实现不应该在同一个接口的子类中，或者你可能需要在该接口中使用两种不同的方法
松散地定义合同以允许实施中的一些差异（但只有从客户的角度来看它才有意义！）

Answer 2

您应该描述在什么情况下它将返回给客户端的内容。客户端不需要知道如何处理返回它，但它应该知道某些类型的输入，将返回一些特殊输出。

将来，如果要抛出异常，则必须更改javadoc，以便调用者知道它必须处理异常

Answer 3

通常，您将此放在界面上，界面定义了实现的行为。但是，这里没有严格的规则，如果特定的实现行为不同，您也可以在实现注释上加以区别。这与Java标准库在JavaDoc中的工作方式非常相似。

例如，考虑一下ArrayList：

http://java.sun.com/javase/6/docs/api/java/util/ArrayList.html

有removeAll，它在List中定义并在AbstractCollection中实现

http://java.sun.com/javase/6/docs/api/java/util/List.html#removeAll(java.util.Collection)

http://java.sun.com/javase/6/docs/api/java/util/AbstractCollection.html#removeAll(java.util.Collection)

List类定义它的作用，AbstractCollection类定义它的特定行为。

文档是一种工具，所以在你觉得合适的时候使用它们，这个工具最重要的部分就是它们保持最新状态 - 所以过度记录会导致后来的麻烦，在记录下也是如此！一般来说，也尽量保持你在每个方法中编写的代码简洁明了，尽可能没有副作用，这样你就可以阅读代码并理解它的意义，而不必过多依赖周围的文档

Answer 4

看起来非常适合Javadoc：

/**
 * The method returns associations where the given ID is the parent and the association is of type 'type'. <br>
 * ID is required, but if type passed in is NULL, then I will return ALL associations where the ID is the parent.<br>
 *<br>
 * Subclasses may  throw an IllegalArgumentException if type is NULL.<br>
 * @param id Parent identifier
 * @param type the type of association
 * @return the Association or null if type is null
 */
public int getTotalAssociationsAsParent(Long id, Long type)

我希望过去曾经拥有过这种文件。

我经常得到：

/**
 * get the total associations as parent 
 * @param id the id
 * @type the type
 */ 
public int getTotalAssociationsAsParent(Long id, Long type);

哪个没用。

在javadoc中记录逻辑

4 个答案: