Are comments needed with method headers in an interface?

[taichibandit]

Hi guys,

Is it good practice to include comments with method headers in an interface?
As the methods in my project are fully commented in the client class any further
comments in the interface code seem an unnecessary duplication.

Thanks.

[Old Pedant]

<shrug>It usually depends on company policy.</shrug>

Personally, I think it's more important that the comments be in the interface than in the classes. After all, *theoretically* you will have one interface and many classes that implement it. Make much more sense to have the comments in the "one" than in the "many". But let's face it, if you work for a company that says "thou shalt comment to c.y.a." then you do so.

[brad211987]

Much of what I've seen includes the primary documentation in the interface, and any implementation specific details in the implementation classes, as well as a @see tag pointing to the interface. This will provide generic information at the interface level, any extra details at the implementation, an a "see also" link on the generated javadoc.

[Old Pedant]

Yeah, forgot about @see. Good idea. Even if the class doesn't have any special implementation details, you could still at least have the @see to point to the right file, etc.

[cs_student]

If you really want to see one of the best ways to document your code, just look at the java api source (http://download.java.net/jdk6/source/). It is documented wonderfully.

However, if you are not creating a large project, such extensive documentation may not be necessary. Non-the-less, it's great code to learn from.

Your question is really quite subjective. Only through experience will you find what suites you the best.

Regards,


cs_student

[taichibandit]

Thanks Guys, :thumbsup:

I'll go with general documentation in the interface and put implementation specific detail in the client classes.