• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Write good comments and produce good javadoc

 
Ranch Hand
Posts: 102
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Greenhorn
Posts: 4
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
author and jackaroo
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Ranch Hand
Posts: 73
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 ]
 
Ranch Hand
Posts: 442
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Posts: 12200
280
Mac IntelliJ IDE Firefox Browser Oracle C++ Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
reply
    Bookmark Topic Watch Topic
  • New Topic