NX: Should I reformat the provided interfaces comments?

[Jacques Bosch]

Assignment: Bodgitt and Scarper
The DBAccess interface I got with my assignment have some comments but they do not adhere to the javadoc standards. Should I reformat them to valid javadoc comments, or leave them as is?
Thanx much.
Jacques

[Philippe Maquet]

Hi Jacques,
Welcome to this forum !
Reading this :

javadoc style comments must be used for each element of the public interface of each class. You must create a full suite of documentation for the classes of the completed project. This must be generated using the tool "javadoc" and must be in HTML format. Provide javadoc documentation for all classes you write.

I think you should be OK by formatting the provided DBAccess comments in the javadoc style. And as it can be interpreted belonging to that "must-be", I wouldn't hesitate.
Best,
Phil.

[Ken Krebs]

Jacques,
I can confirm that this is OK to do as I did it and passed with a high mark. I agree with Phil that it is probably best to do it.

[Jacques Bosch]

Hi Phil & Ken.
Thanx for the welcome. I think I'll be depending on this place to clear up a number of things for my asignment.
That is what I was thinking. I'll go ahead and do it like that.
Ken, by the way, +/- how many hours did you spend on your asignment? I'm hoping to finish within a month or so if possible. But I have to put in my normal hours for my job still.
Thanx much!
Jacques

[Ken Krebs]

Jacques,
I spent way more time on it than I should have (automatic failure paranoia), approx. 2 full months of work spread over about 4 months time. I was very careful and took a perfectionist attitude and was rewarded with a high score. If I was more experienced and worked at it full time, I probably could have done it in a month. Doing it in a month in your spare time seems very optimistic to me, but hey maybe you are that good.

[Jacques Bosch]

Ha ha.
Maybe not......!!!

[Jacques Bosch]

OK, Further to the comments issue.
So I reformat the comments in the provided DBAccess interface to javadoc standards.
Now my Data class impliments DBAccess. Do I have to duplicate the javadoc comments in the Data class where they are the same as the DBAccess interface's?
Thanx.

[George Marinkovich]

Originally posted by Jacques Bosch:
Now my Data class impliments DBAccess. Do I have to duplicate the javadoc comments in the Data class where they are the same as the DBAccess interface's?

I duplicated them in the Data class. An alternative is to leave the javadoc formatted method comments blank or use the javadoc tag {@inheritDoc} for all the methods inherited from DBAccess. This works perfectly fine as far as your generated javadoc documentation goes. But I didn't like it because it left the Data class looking like this:

...
    /**
     * {@inheritDoc}
     */
    public synchronized int[] find(String[] criteria)
            throws RecordNotFoundException {
        ...
    }
...

or in my opinion, even worse:

...
    public synchronized int[] find(String[] criteria)
            throws RecordNotFoundException {
        ...
    }
...

The arguments for doing this go something like this:

It avoids the danger of out-of-synch comments since the comment is only maintained in the interface or the base class.

It's less work.

Someone looking for a comment will know that since this class implements an interface or extends a base class, that of course, the real comment will be found in the interface or the base class.

I find the first two arguments to be very sound (especially the second argument), but I am so annoyed with the third argument that on balance I came down on the side of including the full comment everywhere it is needed.

[Philippe Maquet]

George:
I duplicated them in the Data class. An alternative is to leave the javadoc formatted method comments blank or use the javadoc tag {@inheritDoc} for all the methods inherited from DBAccess. This works perfectly fine as far as your generated javadoc documentation goes.

I fully agree with what George wrote. Now there is a third alternative path which is defendable too IMO : writing *different* comments in the javadoc of the class. Provided comments are *interface* documentation, meaning they were written at the *specification* level. At the *class* level, you may add *implementation* level comments, which don't really contrast with the interface doc of course, but may complete it. Example : if you implemented a cache in Data, telling that your readRecord() method uses that cache doesn't hurt.
Regards,
Phil.
[ January 06, 2004: Message edited by: Philippe Maquet ]

[Jacques Bosch]

Thanx guys for the insight. I'll think about it a bit, but feels right to make duplicates.
Jacques