Are javadoc comments necessary for instance variables and constructors?

[DWW]

I'm new to Java and the whole javadoc doc commenting thing and was curious if its standard practice to doc comment your instance variables and constructors.

I could see doing it for methods but instance variables and constructors seem so obvious (at least for what im doing)

eg say you have a class Toy, would you make a doc comment for the colour, size, weight instance variables? They just seem so obvious to me...

 

[kamper]

It really depends on who you think will be reading your javadocs. If you're just writing code for yourself javadoc comments probably aren't really necessary (but normal comments are a must, of course). If you're writing documentation for other programmers that will be modifying your code then you probably can't comment too much (as long as the comments are high quality). If you're documenting for other programmers that will use your classes but don't need to see the source code then doing public and protected methods/variables is a good idea. Basically anything that someone might want to use needs to be documented. Take a look at the java api docs. It's entirely possible (and indeed desirable) to program based on them rather than inspecting the source code.

To get to the original question more specifically: your instance variables should probably be private (protected is ideal, except for the damn package-access rules :|) and so javadocs aren't really neccessary. If your code is complex you will thank yourself for putting regular comments on all instance variables.
Constructors are just like other methods and indeed are even more important. Without a doubt they should be documented.

They just seem so obvious to me...

Heh, you say that now. If you're just fooling around and won't keep the code for long that might be fine but if you use this code for anything long term you will very quickly forget what everything means.

Good luck.

 

[DWW]

instance variables are always private (for this piece)
so really i guess no javadoc needed since that is what is used by other coders and no other coder will need to know about private members i guess...

as for constructor doc commenting i just thought a constructor is obvious (what it does) so you didnt need to javadoc it

if you have class String and you are implementing it in your project you should know intuitively that calling new String() just creates an object of that type

all other methods? sure i would doc comment...but constructors which are obvious? hrmmm

 

[Barnaby W. Füi]

Well obviously a comment like /* this constructs the instance */ is worthless, but you can explain what the arguments represent, and how the constructor goes about setting up the object. If there is truly nothing to explain about the constructor, then don't. Less is more.

The constructor doesn't really "create" anything, rather it is called to "prepare" the object, after the object has been allocated. Or along those lines anyways, I'm not a Java programmer.