This week's book giveaway is in the Servlets forum.
We're giving away four copies of Murach's Java Servlets and JSP and have Joel Murach on-line!
See this thread for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes How much Javadoc should we write for the assignment? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Murach's Java Servlets and JSP this week in the Servlets forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "How much Javadoc should we write for the assignment?" Watch "How much Javadoc should we write for the assignment?" New topic
Author

How much Javadoc should we write for the assignment?

Alexandru Dragoi
Ranch Hand

Joined: May 09, 2008
Posts: 30
I guess that writing Javadoc is mandatory for the exam, but how much should we make use of it?
For public APIs I see the use of these type of comments, but is there a rule that compels us to write Javadoc for every public method (or even for private methods)?
In the exam book that I use to prepare myself I see extensive use of Javadoc comments.

If I will lose points because I do not document every method that I write, then this will be a terrible scenario: I will have to write redundant comments, where method names and parameters names (and even the code itself) are self explanatory.


Alex Dragoi, SCJP 1.4, OCPJP 6
K. Tsang
Bartender

Joined: Sep 13, 2007
Posts: 2224
    
    7

For me I write javadoc for all classes, methods, instance variables, etc everything. All access modifiers: private, default, protected and public.

As for how detail, the standard is fine. But for the Data class (the place where the locking, searching etc) probably more details.


K. Tsang JavaRanch SCJP5 SCJD/OCM-JD OCPJP7 OCPWCD5
Alexandru Dragoi
Ranch Hand

Joined: May 09, 2008
Posts: 30
Ok thanks, if that's what they want me to do, that is what I'll do!
Tim Cooke
Bartender

Joined: Mar 28, 2008
Posts: 798
    
  38

I understand that this post is in the Certification forum so you're probably more interested in what the Marking Criteria guidelines are for JavaDocs. I cannot help you there.

However, I do tend to take the opposite view of things than K Tsang does. I write as little JavaDoc as possible. Which means with the exception of 'public' API's I mostly write none. I'll back up my viewpoint with some examples:

Example1: Instance variables.

The JavaDoc tells us nothing about the variable that the variable name doesn't. But now my variable declaration takes up 4 times as much space as it needs.

Example2: Field accessors.

The JavaDoc tells us nothing about the method that the method signature doesn't. But now my accessor code occupies over double the amount of space it needs to.

Example3: Methods

In this case you might think that the JavaDoc has value as it describes what the method does. While this is true I don't see it as the positive point you might think. I see that the JavaDoc is covering up the fact that we have a poorly named method that does not reveal its intent with a meaningful name. For this example I would refactor to the following:

Uncle Bob Martin has a whole section in his book Clean Code about JavaDoc, Comments, and naming. Well worth a read.


Tim Driven Development
Alexandru Dragoi
Ranch Hand

Joined: May 09, 2008
Posts: 30
This is also what I wanted to emphasize in my original post.
Code is changing rapidly these days, and you do not have time to update also the documentation in order to keep up with the code.
It is better to concentrate on how to make your code to be easy to read rather than to add tons on documentation.

But I guess that for such a small project (required by OCMJD), writing a lot of Javadoc (even for privates), it is not such a pain.
K. Tsang
Bartender

Joined: Sep 13, 2007
Posts: 2224
    
    7

Tim's comments are also correct. Yet I doubt file size is an issue. A one liner plus those @XXX attributes eg @param, @throw, @return etc are alright.

When you are done with the javadoc, you have the option to generate just the public methods or all (including private).

The javadoc portion is part of the "documentation" criteria, which I believe includes the user guide, the choices.txt (probably most important doc) and javadoc.
Tim Cooke
Bartender

Joined: Mar 28, 2008
Posts: 798
    
  38

Alexandru Dragoi wrote:and you do not have time to update also the documentation in order to keep up with the code

It's potentially worse than that. Take this example again:

Let's say that the business decides that it's not blue Widgets that are important anymore, it's red ones. The developer comes along and finds that this method is tasked with finding the blue Widgets, thinks "great, all I need to do is change this method to find red Widgets instead". This will almost certainly be the result:

It works! You're happy. QA are happy. The Business Analyst is happy. The customer is happy. Job done. Move on.

But what's wrong with this picture? That's right, the JavaDoc still says it's counting blue Widgets. Now the documentation is lying to you, which is much much worse than having no documentation at all. You might think this JavaDoc neglect is laziness. Maybe it is. But the reality is that this happens all the time.

I'd rather have no JavaDoc than JavaDoc that lies to me.
Tim Cooke
Bartender

Joined: Mar 28, 2008
Posts: 798
    
  38

K. Tsang wrote:Yet I doubt file size is an issue.

No. File size is not the issue. Code readability is the issue. When there's lots of unnecessary JavaDoc and Comments it takes a good deal of cognitive load to visually sift the Wheat (code) from the Chaff (redundant comments) which takes away from your ability to think about what code is doing and what you're supposed to be doing with it.
Alexandru Dragoi
Ranch Hand

Joined: May 09, 2008
Posts: 30
Well it seems that they have strict requirements for the exam. I found this forum discussion, Javadoc for getters/setters:
javadoc style comments must be used for each element of the public interface of each class


Public, protected and package-private are part of the public interface for each class. At least they do not require to document also private members...
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: How much Javadoc should we write for the assignment?
 
Similar Threads
Documentation guidelines
Documentation Comments (scjd)
Javadoc private state and methods.
Does your company require documentation? If so, what kind?
Javadock for getters/setters