java - 在 javadoc 中记录逻辑

Question

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

public int getTotalAssociationsAsParent(Long id, Long type);

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

我的问题是应该在哪里记录这种类型的逻辑？我犹豫是否将其放入接口(interface)的 javadoc 中，因为这会限制所有实现类以遵守该逻辑。也许在将来，我会有一个 Impl 类，如果 type 为 NULL，它会抛出 IllegalArgumentException。

但是，如果我将它放在 Impl 类中的非 javadoc 中，则此方法的使用者将不知道该方法在 NULL 类型下的行为方式。

Answer 1

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

但是，如果您觉得此方法的不同实现确实有空间，您有一些选择:

重新考虑你的设计——也许这些实现不应该在同一个接口(interface)的子类中，或者你可能需要在该接口(interface)中使用两个不同的方法

松散地定义契约(Contract)以允许在实现中存在一些差异(但前提是从客户的角度来看它是有意义的!)