javadoc中的java文档逻辑

Question

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

public int getTotalAssociationsAsParent(Long id, Long type);

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

我的问题是，这种逻辑应该记录在哪里？我不太愿意把它放在接口的javadoc中，因为这会限制所有实现类遵守该逻辑。也许在将来，我会有一个Impl类，如果type为NULL，它会抛出一个IllegalArgumentException

然而，如果我把它放在Impl类的非javadoc中，那么这个方法的使用者将不知道该方法在NULL类型下的行为

Answer 1

一般来说，你把它放在接口上，接口定义了实现的行为。但是，这里没有硬性规定，如果某个特定实现的行为不同，您也可以在实现注释中添加该差异。这与Java标准库在JavaDoc中的工作方式非常相似

考虑，例如，ARARYLIST:

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 2

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

将来，如果你想抛出一个异常，你必须修改你的javadoc，这样调用者就可以知道它必须处理一个异常

Answer 3

非常适合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);

这是没有用的

Answer 4

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

然而，如果您觉得这种方法的不同实现确实有一席之地，那么您有一些选择：

• 重新考虑你的设计——也许这些实现不应该在同一个接口的子类中，或者你需要在该接口中使用两种不同的方法
• 松散地定义契约，以允许在实现中存在一些差异（但前提是从客户的角度来看它是合理的！）