Forums Register Login

Documentation guidelines

+Pie Number of slices to send: Send
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
+Pie Number of slices to send: Send
 

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.
+Pie Number of slices to send: Send
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 ]
Did you just should on me? You should read this tiny ad:
a bit of art, as a gift, the permaculture playing cards
https://gardener-gift.com


reply
reply
This thread has been viewed 751 times.
Similar Threads
Coding Standards
javadoc comments
assistance with javadoc
NX: Bext free style checker ?
Class level comments
More...

All times above are in ranch (not your local) time.
The current ranch time is
Mar 28, 2024 16:10:01.