Documentation guidelines

Hi,

I found correctly following the developer documentation (javadoc) is challenging.

I am using CheckStyle and Sun's DocCheck tool to check my documentation and comment in code. These tools report such things as "missing @see tag", "missing javadoc comment" for get/set methods.

I personally do not see a need to document get/set methods, provided that they have intention revealing names. I also do not see why I have to use @see tag in methods and package documentation, either.

However, I am not sure whether the examiner would run some tool and deduct points on documentation, depending on how many errors the tool reports. I would think that unfair, after all comment supposes to be minimal and efficient.

I just thought to ask you how much comment do you provide?
Thanks.
Yan

Originally posted by Yan Zhou:
Hi,

I found correctly following the developer documentation (javadoc) is challenging.

I am using CheckStyle and Sun's DocCheck tool to check my documentation and comment in code. These tools report such things as "missing @see tag", "missing javadoc comment" for get/set methods.

I personally do not see a need to document get/set methods, provided that they have intention revealing names. I also do not see why I have to use @see tag in methods and package documentation, either.

However, I am not sure whether the examiner would run some tool and deduct points on documentation, depending on how many errors the tool reports. I would think that unfair, after all comment supposes to be minimal and efficient.

I just thought to ask you how much comment do you provide?
Thanks.
Yan

Hi, Yan. The requirement for javadoc is a very strict one. It uses the word must to state that every public member of class must have javadocs. Even one missing javadoc will result in automatic failure. The instructions are very strict on documentation, that is why I am going back and rechecking my documentation very carefully to make sure I missed no public member.

Yan,
Documentation is as important as the code itself. You don't have to provide and use all tags. Some of the tags are required such as @param, @throws, and some are optional such as @see. Bottom line is you must provide adquate documentation for all public methods and variables.
Even if you think getXX() and setXX() are self explaining, if they are not documented, no one will know about thier existence except you.
The purpose of the API is to tell other developers what does your code provide without looking at the code.
[ September 29, 2004: Message edited by: Hanna Habashy ]