This week's book giveaway is in the JavaScript forum.
We're giving away four copies of JavaScript Promises Essentials and have Rami Sarieddine on-line!
See this thread for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes NX: Should I reformat the provided interfaces comments? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of JavaScript Promises Essentials this week in the JavaScript forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "NX: Should I reformat the provided interfaces comments?" Watch "NX: Should I reformat the provided interfaces comments?" New topic
Author

NX: Should I reformat the provided interfaces comments?

Jacques Bosch
Ranch Hand

Joined: Dec 18, 2003
Posts: 319
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


Jacques<br />*******<br />MCP, SCJP, SCJD, SCWCD
Philippe Maquet
Bartender

Joined: Jun 02, 2003
Posts: 1872
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
Ranch Hand

Joined: Nov 27, 2002
Posts: 451
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.


kktec<br />SCJP, SCWCD, SCJD<br />"What we observe is not nature itself, but nature exposed to our method of questioning." - Werner Heisenberg
Jacques Bosch
Ranch Hand

Joined: Dec 18, 2003
Posts: 319
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
Ranch Hand

Joined: Nov 27, 2002
Posts: 451
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
Ranch Hand

Joined: Dec 18, 2003
Posts: 319
Ha ha.
Maybe not......!!!
Jacques Bosch
Ranch Hand

Joined: Dec 18, 2003
Posts: 319
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
Ranch Hand

Joined: Apr 15, 2003
Posts: 619
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:

or in my opinion, even worse:

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.


    Regards, George
    SCJP, SCJD, SCWCD, SCBCD
    Philippe Maquet
    Bartender

    Joined: Jun 02, 2003
    Posts: 1872
    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
    Ranch Hand

    Joined: Dec 18, 2003
    Posts: 319
    Thanx guys for the insight. I'll think about it a bit, but feels right to make duplicates.
    Jacques
     
    I agree. Here's the link: http://aspose.com/file-tools
     
    subject: NX: Should I reformat the provided interfaces comments?