【问题标题】：Why Java interfaces have descriptions in docs为什么 Java 接口在文档中有描述
【发布时间】：2015-03-14 11:45:57
【问题描述】：

我知道接口内部只有方法声明，并且只有在某些类实现接口时才提供它们的实现（我不是在谈论默认方法或功能接口）。

问题是：为什么 Java 文档、教程、书籍或其他信息源提供接口方法的描述？例如，http://docs.oracle.com/javase/7/docs/api/index.html?java/util/List.html 提供了对List 接口方法的完整描述，但如果它只是一个接口，那么这些方法不应该提供任何功能，那么这些文档中描述了什么？

【问题讨论】：

如果没有文档，如果我有 List，我怎么知道会发生什么行为？
你的意思是：如果实现了该方法应该做什么？
嗯，我的想法差不多，但看起来有点太抽象了
你已经知道接口用于从一个类到另一个类进行通信。因此，为两个类之间的通信创建了接口，这些类的通信方法已经在这个唯一接口中定义。这意味着如果一个接口定义了一些方法，它只能用于那些需要它们的类。例如我想搜索一些东西，然后我可以使用 google（搜索界面）或 yahoo（搜索界面）或 bing（再次搜索界面）。祝你好运

标签： java syntax interface

【解决方案1】：

描述是接口对象及其方法的目标，如果没有描述，你在实现这个接口对象的时候就不知道在你的方法中怎么写。

例如方法 void clear() 是什么？

选项 1) 删除所有对象

选项 2) 删除最后一个插入列表

选项 3) 删除重复对象

等等..

当然这是一个简单的例子，你可以猜到 clear() 的目标是选项 1，但有时它要复杂得多。

【讨论】：

我接受这个答案，因为这对我来说似乎是最清楚的，而且这个例子也很清楚。但我也喜欢@KrishPrabakar 的回答，因为它引用了 Effective Java。谢谢大家。

【解决方案2】：

因为您必须清楚地指定接口背后的动机以及调用者和实现者的契约是什么。

也就是说，接口中的 cmets 面向两种受众：调用者和实现者。双方都应该知道他们可以期待什么，他们应该如何行事。

显然，就像普通类一样，接口中的文档应该遵守标准，JavaDoc 的规则。

【讨论】：

【解决方案3】：

Joshua Bloch (Effective Java) - 如果 API 要可用，则必须记录在案

除非您记录您的接口方法，否则其他人（API 用户）不会知道 -

它做什么（不是如何它做什么）
它的先决条件
它的后置条件
它的副作用
它的线程安全

Effective Java - Item 44 说：

方法的文档注释应该简洁地描述合同在方法和它的客户端之间。

记录接口方法还有一个优势：继承使用{@inheritDoc}。

Effective Java - Item 44 说：

Javadoc 具有“继承”方法 cmets 的能力。如果一个 API 元素没有 doc 注释，Javadoc 搜索最多具体适用的文档注释，优先于接口超类。搜索算法的详细信息可以在 Javadoc 参考指南 [Javadoc-ref]。您还可以继承部分使用 {@inheritDoc} 标记的超类型的 doc cmets。这表示，除其他外，该类可以重用来自的 doc cmets 他们实现的接口，而不是复制这些 cmets。这设施有可能减少维护负担多组几乎相同的文档集

【讨论】：

【解决方案4】：

简单。因为，我们需要接口的 javadoc，以便为实现这些接口的 Java 开发人员提供信息。

【讨论】：