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 Importance of complete Javadoc 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 "Importance of complete Javadoc" Watch "Importance of complete Javadoc" New topic
Author

Importance of complete Javadoc

Nicolas Zozol
Ranch Hand

Joined: Oct 13, 2009
Posts: 33
Hi,
I submitted my work at 23h58 and didn't have time to put complete javadoc on getters/setters in about 30% of the project.
Do you think it will have an impact ? I think it's the main problem of the project and it makes a kind of stupid stress.


Robusta Web Library : Open Source for REST & Java
Mxolisi Veco
Ranch Hand

Joined: Jan 14, 2010
Posts: 59
Good day.
If the getter or setter is simple, I do not think the absence of javadoc is going to have anybad impact. So no need to stress.
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5126
    
  12

I documented all methods, so getters and setters are included. Just for the sake of the assignment, because in my opinion documenting getters/setters have not a lot of added value, certainly not if you have good names for your methods. I think you can use the time to complete the javadoc for all getters/setters better for documenting "real" methods.
I don't think you'll fail automatically for not documenting all getters/setters.


SCJA, SCJP (1.4 | 5.0 | 6.0), SCJD
http://www.javaroe.be/
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2258
    
    3

Roel De Nijs wrote:I documented all methods, so getters and setters are included. Just for the sake of the assignment, because in my opinion documenting getters/setters have not a lot of added value, certainly not if you have good names for your methods. I think you can use the time to complete the javadoc for all getters/setters better for documenting "real" methods.
I don't think you'll fail automatically for not documenting all getters/setters.


Agreed.

These getter/setter methods do not have to be so detailed, because any developer should be able to know what these methods are for. Something like this should be enough:



So Nicolas, you ended up not even including any JavaDoc comments on these methods?


Cheers, Bob "John Lennon" Perillo
SCJP, SCWCD, SCJD, SCBCD - Daileon: A Tool for Enabling Domain Annotations
Nicolas Zozol
Ranch Hand

Joined: Oct 13, 2009
Posts: 33
Unfortunately, not at all for about 20% of them. I made this exam the year of a new job, new house and first baby. Not the right moment !
Eduard Mamedov
Greenhorn

Joined: May 20, 2010
Posts: 23
What type of comments add to instance private variables (javadoc or implementation comments)??


SCJP 6
Piotr Nowicki
Ranch Hand

Joined: Jul 13, 2010
Posts: 610

The exact question I've asked myself Eduard :-)

I think that in K&B SCJP book in late chapters (related to SCJD) I've seen they add implementation comments to the private variables. Which is somewhat logical, as private variables are available only for the developers, and will not be used by the outer world for which the javadoc is basically made for.

On the other hand in Java Code Conventions from the Sun/Oracle website in the example code on the last pages, shows that they have added a standard javadoc comments to the private variables.

After some thinking I've decided to add a standard Javadoc comment even for private members, as this gives me the ability to generate the javadoc even for the private methods and explore them in the same way the rest of the documentation (which is an option in javadoc).

Therefore I think the javadoc comment does not harm and brings some (small, but always!) added value.

Cheers!


OCP Java SE 6 Programmer, OCM Java SE 6 Developer, OCE Java EE 6 JSPSD, OCE Java EE 6 EJBD, OCE Java EE 6 JPAD, Spring 3.0 Core Professional.
Eduard Mamedov
Greenhorn

Joined: May 20, 2010
Posts: 23
Some of my variables have specific implementation details of how it used by methods.... Now i have to type of comments for such variables: javadoc - simple description, and implementation comments.... is this normal to use two type of comments for some variables? :)
Hey, Pedro, man... I see you already at final stage of your assignment. Good luck in submiting :)
Piotr Nowicki
Ranch Hand

Joined: Jul 13, 2010
Posts: 610

Didn't see implementation + javadoc codes for class variables. For classes, yeah - sure, but for variables... no. Of course that doesn't mean that you shouldn't do it :-)

In your place I would try to think if such a situation doesn't mean you should rethink your design or at least move some of those comments to the place where you use this variable - to the method.
Do you think it would make sense in your case?

Cheers!

PS. Yea, thanks - I'm just struggling with the choices.txt which is over 55kB right now... But I will reduce it in the post-production phase. At this moment I just want to make sure I remember and understand every piece of the code :-)
Eduard Mamedov
Greenhorn

Joined: May 20, 2010
Posts: 23
Pedro Kowalski wrote:Didn't see implementation + javadoc codes for class variables. For classes, yeah - sure, but for variables... no. Of course that doesn't mean that you shouldn't do it :-)

In your place I would try to think if such a situation doesn't mean you should rethink your design or at least move some of those comments to the place where you use this variable - to the method.
Do you think it would make sense in your case?

Cheers!

PS. Yea, thanks - I'm just struggling with the choices.txt which is over 55kB right now... But I will reduce it in the post-production phase. At this moment I just want to make sure I remember and understand every piece of the code :-)


I have some additional information to my record map(recNo, positions) and to my cache map(recNo, String[]). In my methods i directly use this variables. Hmm, I think you are right, this bad style to comment variables in my way, ... it's better to move this information to choices text file.
Piotr Nowicki
Ranch Hand

Joined: Jul 13, 2010
Posts: 610

BTW: I think that if you must add a comment to the private variable and not to the method which operates on it, you might add some implementation comments as a javadoc as well.
Why? Well, I think javadoc is supposed to be non-technical (non-implementation detailed), as the artifacts documented are mainly public. It means that you describe a contract, how to use your class and should not focus on inner details.
However, private variables are very implement-oriented, as no one other has access to them. I think that javadoc then can be more detailed, as only the developer who works with the class itself will use this kind of documentation.

This is how I see it :-)

Cheers and good luck mate!
Nicolas Zozol
Ranch Hand

Joined: Oct 13, 2009
Posts: 33
Pedro Kowalski wrote:BTW: I think that if you must add a comment to the private variable and not to the method which operates on it

Despite what I've done, I really prefer some docs on getters/setters when I use an API

Pedro Kowalski wrote:
PS. Yea, thanks - I'm just struggling with the choices.txt which is over 55kB right now... B


Oups, mine was not even 2ko. Let's see what will happen.
Roel De Nijs
Bartender

Joined: Jul 19, 2004
Posts: 5126
    
  12

Nicolas Zozol wrote:Oups, mine was not even 2ko. Let's see what will happen.

That's very little to justify all your decisions. 36kB for me
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Importance of complete Javadoc
 
Similar Threads
What exctly the Future class in concurrent package of util?
SCJD begins
javadoc
Are you a Javadoc Nazi
Javadoc Question