JavaDocs 的最佳实践——接口、实现或两者兼而有之？答案

【问题标题】：Best Practice for JavaDocs - Interface,Implementation, or Both?JavaDocs 的最佳实践——接口、实现或两者兼而有之？
【发布时间】：2012-07-25 04:45:52
【问题描述】：

我有一个 DAO 接口和 DAO 的实现。界面中的 JavaDocs 是 Netbeans 向实现 DAO 方法的客户端显示的内容。

显然我需要在界面中维护 JavaDocs。但是它的实施呢？一方面，放在那里很方便，但另一方面，它是重复的，需要在两个地方进行维护。

只是想知道其他 Java 开发人员在做什么。

【问题讨论】：

stackoverflow.com/questions/3061387/…

标签： java

【解决方案1】：

如果实现方法不提供自己的 Javadoc，仍然会有指向接口方法文档的链接。我一直不明白为什么 Eclipse 会插入 /* (non-Javadoc) @see ... */，因为 Javadocs 会自动引用接口的文档。

例子：

public interface Named {
  /** Returns the name. */
  public String getName();
}

public class Thing implements Named {
  // note no Javadocs here
  public String getName() {
    return "thing";
  }
}

运行javadoc 后，Thing.getName 的 Javadocs 为：

getName

public java.lang.String getName()
    Description copied from interface: Named
    Returns the name.
    Specified by:
        getName in interface Named

【讨论】：

“我从来不明白为什么 Eclipse 会插入”因为这样您就可以简单地 Cmd+单击引用的类并立即访问文档。对 JavaDoc 没用，但对开发有用。
@mmlac 大多数 IDE (Eclipse) 都有指向定义接口/类的链接

【解决方案2】：

接口应该有合约的所有信息，基本上方法是做什么的，参数的描述，返回值等等。

除非接口描述中有一些额外信息不清楚（很少有），否则实现文档应该简单地链接到接口方法。

这是我从栅栏的实施者和客户端发现的最有用的格式。

【讨论】：

【解决方案3】：

在我的项目中，Eclipse 会自动创建如下文档：

     /* (non-Javadoc)
     *  @see com.comp.SomeInterface#method(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
     */
    @Override
    public void method(HttpServletRequest arg0, HttpServletResponse arg1)
            throws Exception {
        // TODO Auto-generated method stub

    }

我们已经使用 Ant 任务创建了 javadoc，因此它会创建到界面的链接。

【讨论】：

界面的链接将在没有 Eclipse 生成的文档的情况下出现。