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.

http://stackoverflow.com/questions/3061387/should-javadoc-comments-be-added-to-the-implementation — andersoj, Jul 26 '12 at 14:51

Steve Kuo · Answer 1 · 2012-07-26T16:19:34.657

9

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

edited Jul 26 '12 at 16:19

answered Jul 26 '12 at 16:12

Steve Kuo

61,876
75
195
257

2

"I never understood why Eclipse inserts" Because then you can simply Cmd+click onto the referenced class and get immediate access to the docs. Not useful for JavaDoc, but useful for development. – mmlac May 13 '14 at 21:44
1

@mmlac Most IDEs (Eclipse) has a link to go to the defining interface/class – Steve Kuo Mar 15 '16 at 20:21

score 4 · Answer 2 · answered Jul 26 '12 at 14:52

The interface should have all the information about the contract, basically what the method does, the description of parameters, return values and so on.

Unless there's some extra information that isn't clear from the interface description (there rarely is), the implementation documentation should then simply link to the interface method.

This is the format that I've found the most useable from both the implementor and the client side of the fence.

Nandkumar Tekale · Accepted Answer · 2012-07-26T15:18:06.370

3

In my project, Eclipse automatically creates documentation as below :

     /* (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

    }

We have created javadoc using Ant task, so it creates link to the interface.

edited Jul 26 '12 at 15:18

answered Jul 26 '12 at 15:06

Nandkumar Tekale

16,024
8
58
85

2

The link to the interface will be there without the Eclipse generated docs. – Steve Kuo Jul 26 '12 at 15:09

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

3 Answers3