Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documentation guidelines

 
Yan Zhou
Ranch Hand
Posts: 137
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Anton Golovin
Ranch Hand
Posts: 527
1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Hanna Habashy
Ranch Hand
Posts: 532
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic