在 javadoc 中记录逻辑
我有一个关于在 javadocs 中记录逻辑的位置的问题。例如，我在接口中有以下方法签名：
public int getTotalAssociationsAsParent(Long id, Long type);
该方法返回关联，其中给定 ID 是父级，且关联的类型为“type”。 ID 是必需的，但如果传入的类型为 NULL，那么我将返回 ID 为父级的所有关联。
我的问题是这种类型的逻辑应该记录在哪里？我犹豫是否将其放入接口的 javadoc 中，因为这会限制所有实现类遵守该逻辑。也许将来，我会有一个 Impl 类，如果类型为 NULL，它会抛出 IllegalArgumentException。
但是，如果我将其放在 Impl 类中的非 javadoc 中，则该方法的使用者将不知道该方法对于 NULL 类型的行为如何。
I have a question about where to document logic in javadocs. For example, I have the following method signature in an interface:
public int getTotalAssociationsAsParent(Long id, Long type);
The method returns associations where the given ID is the parent and the association is of type 'type'. ID is required, but if type passed in is NULL, then I will return ALL associations where the ID is the parent.
My question is where should this type of logic be documented? I hesitate putting it in the javadoc of the interface because that sort of constrains all implementing classes to adhere to that logic. Maybe in the future, I'll have an Impl class that throws an IllegalArgumentException if type is NULL.
However, if I put it in non-javadoc in the Impl class, then consumers of this method won't know how the method behaves with a NULL type.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（4）
你描述的是方法的接口契约，所以它确实属于Javadoc。接口的客户端需要知道该接口履行的确切合同。如果派生类以不同方式实现该方法，则它实际上破坏了契约，从而破坏了里氏替换原则。
但是，如果您觉得确实可以使用此方法的不同实现，那么您有一些选择：
What you describe is the interface contract of the method, so it belongs to the Javadoc indeed. Clients of the interface need to know the exact contract this interface fulfills. If a derived class implements the method differently, it effectively breaks the contract, thus breaks the Liskov Substitution Principle.
However, if you feel there really is place for different implementations of this method, you have some choices:
您应该描述在什么情况下它将返回给客户端什么。客户端不需要知道你如何处理返回它，但它应该知道通过某些类型的输入，将返回一些特殊的输出。
将来，如果你想抛出异常，你必须更改你的javadoc，以便调用者知道它必须处理异常
You should describe what it will return to the client in what case. The client does not need to know about how you process to return it but it should know with some kinds of input, some special output will be returned.
In the future, if you want to throw an exception, you have to change your javadoc so that the caller can know it has to handle an exception
通常，您将其放在接口上，接口定义实现的行为。然而，这里没有硬性规定，如果特定实现的行为不同，您也可以将这种差异放在实现注释中。这与 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 类定义了它的特定行为。
文档是一种工具，因此请根据需要使用它们，该工具最重要的部分是它们保持最新状态 - 因此，过度记录可能会导致以后令人头痛，记录不足也是如此！一般来说，还要尽量保持在每个方法中编写的代码简短、简洁，并尽可能没有副作用，这样您就可以阅读代码并理解它的含义，而不必过多依赖周围的文档。
In general you put this on the interface, the interface defines the behaviour of the implementations. However there is no hard and fast rule here, if a particular implementation behaves differently you can also put that difference on the implementation comment. This is very similar to how the Java Standard Library does things in their JavaDoc.
Consider, for example, ArrayList:
http://java.sun.com/javase/6/docs/api/java/util/ArrayList.html
has removeAll, which is defined in List and implemented in 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)
The List class defines what it does, the AbstractCollection class defines it's particular behaviour.
Docs are a tool, so use them as you feel fit, the most important part of this tool is that they're kept current - so over documenting can cause headaches later, under documenting too! In general also try to keep the code you write in each method short and concise and as free of side effects as possible, this way you're able to read the code and understand what it means to do without so much dependance on the surrounding documentation.
看起来非常适合 Javadoc：
我希望自己过去也有这样的文档。
我通常会得到：
这没有用。
Looks perfect for Javadoc:
I wish to have had this kind of doc in the past my self.
I usually get:
Which is not useful.