File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes javadoc-umenting privates? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "javadoc-umenting privates?" Watch "javadoc-umenting privates?" New topic
Author

javadoc-umenting privates?

Serkan Yazici
Ranch Hand

Joined: Apr 24, 2004
Posts: 33
Hi guys (and gals),

This is my first post in this forum, yet I feel like I've already know most of you by reading the forum inside out the past two weeks. A big thanks for all the insights you've given me.

Now, I'm almost done with my project but I'm not sure if should generate javadocs for my privates (...really, I mean methods and attributes...). I know it is not the general practice for public APIs that you provide to others, but for this project, I think javadoc is also for giving the assesor an idea on what the classes do and how. And I think the documentation should be more of a technical one. Most of the real work done by my classes is using private members. For example, my Client class that is responsible for creating/displaying/running the client window has only one public member: createGUI. All the work is done internally.

Oh, my instructions say:
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.


Now that says, "must be used for each element of the public interface", but doesn't say "must not be used for other levels".

What do you think?

And thanks again for all the info here.


-- SCJP 1.4 (98%), SCJD (98%), SCWCD (96%), OCA Dev (97% avg.), SCBCD (97%), SCJP 1.5 BETA (90%)<br />-- OCP Dev (maybe), MCDBA (probably) SCEA (eventually)<br />-- Haven't tried Firefox yet? Free, open, secure, fast, tabified, and slick!<br />-- <a href="http://www.mozilla.org/products/firefox/" target="_blank" rel="nofollow">http://www.mozilla.org/products/firefox/</a>
Andrew Monkhouse
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11476
    
  94

Hi Serkan,

Welcome to JavaRanch and this forum.

I am one of those who does document all levels of all my classes, and I did so in my submission (and got 100% for documentation). But I know that others have submitted without providing javadoc for non public methods and they also received 100% for documentation. So it appears that you don't have to do this.

I would still recommend having some documentation on all your methods, but you may not need to have full javadoc style comments.

Regards, Andrew


The Sun Certified Java Developer Exam with J2SE 5: paper version from Amazon, PDF from Apress, Online reference: Books 24x7 Personal blog
Serkan Yazici
Ranch Hand

Joined: Apr 24, 2004
Posts: 33
Thanks Andrew,

Good to be here.

I think I should have rephrased my question as "should I generate javadocs for private classes and members?". I commented everything in the code (javadoc style) - God, it took me longer than coding the stuff. I wasn't sure whether or not to expose them in the generated documents.

Anyways, after thinking about it a little more, I settled for generating javadocs for all package-level and public classes/members (I don't really have any protected members).

Thanks for your reply. Now back to completing and polishing up the user guide and design choices.

-- Serkan
Nathaniel Stoddard
Ranch Hand

Joined: May 29, 2003
Posts: 1258
I also created javadocs for all levels of my code. I forget whether my final api javadocs were for all levels, or only the public though. I'd imagine at that point it wouldn't matter -- the grader is not likely to notice that some are private when spending her two minutes looking at your javadocs, but will likely notice your thoroughness when browsing your source.


Nathaniel Stodard<br />SCJP, SCJD, SCWCD, SCBCD, SCDJWS, ICAD, ICSD, ICED
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: javadoc-umenting privates?