Importance of complete Javadoc

[Nicolas Zozol]

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.

[Mxolisi Veco]

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]

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.

[Roberto Perillo]

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:

/** The name of the person */
private String name;

/**
 * Gets the name of the person.
 *
 * @return The name of the person.
 */
public String getName() {...}

/**
 * Sets the name of the person.
 *
 * @param name
 *            The name of the person to be set.
 */
public void setName(String name) {...}

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

[Nicolas Zozol]

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]

What type of comments add to instance private variables (javadoc or implementation comments)??

[Piotr Nowicki]

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!

[Eduard Mamedov]

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]

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]

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]

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]

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]

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