Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Write good comments and produce good javadoc

 
frank sun
Ranch Hand
Posts: 102
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
Could anybody provide the suggestion on how to comment the source file and, when how to make the javadoc look better?
Regards!
Frank.
 
Kenneth Christensen
Greenhorn
Posts: 4
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Frank,
I don't know about the javadocs, but about the
comments I think you should write more than 3
comments !!? I wrote about 3-5 comments in my
code and that was not so good, because I got deductions for it - I got 3 deductions for my
documentation
Regards
Kenneth Christensen
SCJP & SCJD
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Frank,
The DockCheck doclet which works as an add on to JavaDoc will show you where your JavaDoc does not meet standards. The JavaDoc home page has this doclet, as well as tutorials on how to write good JavaDoc comments.
Personally I try to write my JavaDoc such that it gives information on how to use the method (or class), or would allow someone to reproduce the functionality of the class if they did not have my code.
Most of my methods do not have embeded comments, but there are a few locations where I felt the code was not self explanitory, so I have added comments there.
Regards, Andrew
 
Thomas Kijftenbelt
Ranch Hand
Posts: 73
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,
A question regarding the javadoc comments: when you implement a method from an interface, do you refer to the javadoc comment of the interface, or do you write a full comment, e.g.

or

I personally would prefer the first option, but is this in line with the SCJD requirements.
Greetings,
TK
[ May 12, 2003: Message edited by: Thomas Kijftenbelt ]
 
Ta Ri Ki Sun
Ranch Hand
Posts: 442
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Thomas Kijftenbelt:
Hi,
A question regarding the javadoc comments: when you implement a method from an interface, do you refer to the javadoc comment of the interface, or do you write a full comment, e.g.

or

I personally would prefer the first option, but is this in line with the SCJD requirements.
Greetings,
TK
[ May 12, 2003: Message edited by: Thomas Kijftenbelt ]


I cant seem to find Sun's doc regarding this, I didn't bookmark it, but this comment from DocCheck's warning supports what I read previously, which is that comments are not required, the standard is to add a comment of this form //Inherited from suncertify.db.DBMain, heres a snippet from DocCheck
Warning Generated for methods without comments that override a superclass method or implement an interface. Such methods need no comments, because it will be inherited. A warning is generated though, so the developer can check to see that a normal comment of the form // Inherited {<from>} is included in the code. Can also be the level assigned to "self-evident" comments using the -evident switch. May be used in the future.

PS Andrew, I cant get DocCheck to run I'll post errors later, do you have it running with 1.4.*?
I think it may have a problem with {@value CONSTANT} tags
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ta Ri Ki,
From the download page:
System Requirements - Version 1.2 or 1.3 (but not yet 1.4) of the JavaTM 2 SDK, Standard Edition (J2SE).

Personally I do have it working with 1.4. I am trying to remember what I did to fix it. I know that Sun were notified (by someone else) of the exact line of code that was causing the problem, and a workaround was given. Obviously Sun are not happy with the workaround, so havent published it, but if you do it yourself, everything seems to work fine.
I am looking for that patch again. Once I have found it I will post it here.
Regards, Andrew
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ta Ri Ki,
Here is the link I was looking for.
Java Forum discussion on checkdoc and Java 1.4
I followed FolkertM's suggestion, and it worked, so I didnt bother asking Sun for their version. I should I guess, just lazy
Regards, Andrew
 
Ta Ri Ki Sun
Ranch Hand
Posts: 442
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Andrew Monkhouse:
Hi Ta Ri Ki,
Here is the link I was looking for.
Java Forum discussion on checkdoc and Java 1.4
I followed FolkertM's suggestion, and it worked, so I didnt bother asking Sun for their version. I should I guess, just lazy
Regards, Andrew

Thanks Andrew, that works , except all my file names are null, so i have to rename them to null.html to read them properly.
does yours do this?
and what does your call to super look like?
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12007
215
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ta Ri Ki,
Sorry, I did not keep my copy of the modification around, so I cannot tell you. I think I used the super(null,null,String,String) format, but I wouldnt put money on it.
Regards, Andrew
 
Ta Ri Ki Sun
Ranch Hand
Posts: 442
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Andrew Monkhouse:
Hi Ta Ri Ki,
Sorry, I did not keep my copy of the modification around, so I cannot tell you. I think I used the super(null,null,String,String) format, but I wouldnt put money on it.
Regards, Andrew

thanks Andrew, I just mailed the guys at javadoc who sent me a licence agreement, so I guess by tomorrow I'll have their version.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic