This week's book giveaway is in the OO, Patterns, UML and Refactoring forum.
We're giving away four copies of Five Lines of Code and have Christian Clausen on-line!
See this thread for details.
Win a copy of Five Lines of Code this week in the OO, Patterns, UML and Refactoring forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Bear Bibeault
  • Ron McLeod
  • Jeanne Boyarsky
  • Paul Clapham
Sheriffs:
  • Tim Cooke
  • Liutauras Vilda
  • Junilu Lacar
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • fred rosenberger
  • salvin francis
Bartenders:
  • Piet Souris
  • Frits Walraven
  • Carey Brown

Documentation guidelines

 
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
 
Ranch Hand
Posts: 531
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.
 
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 ]
 
Drove my Chevy to the levee but the levee was dry. A wrung this tiny ad and it was still dry.
Thread Boost feature
https://coderanch.com/t/674455/Thread-Boost-feature
    Bookmark Topic Watch Topic
  • New Topic