Best Practice for JavaDocs - Interface,Implementation, or Both?

Question

I have a DAO interface and implementation of the DAO. The JavaDocs in the interface are what Netbeans displays to the client implementing the DAO methods.

Obviously I will need to maintain the JavaDocs in the interface. But what about the implementation of it? On one hand, it is convenient to have them there, but on the other hand, it is duplication, and requires them to be maintained in two places.

Just wondering what other Java developers do.

Answer 1

If the implementing method doesn't provide its own Javadoc, there will still be a link to the interface method's docs. I never understood why Eclipse inserts /* (non-Javadoc) @see ... */ as the Javadocs will automatically reference the interface's docs.

Example:

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

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

After running javadoc, Thing.getName's Javadocs are:

getName

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