Java Coding Standards:Documentation

A proper documentation of code ensures better maintainability and code management.Writing documentation may not be fun but it is necessary.The focus is practical tips, practices to be followed religiously while documenting code . When you are a beginner in coding world this seems to be a insignificant and time consuming exercise but as you grow in experience you know how important it is to follow such practices in code, so that relevance and meaning of each part of code become evident to anyone going through the code.
Some documentation tips that may make programmer fraternity happy:

1. Documentation comment should not be more than 80 characters. If it is unavoidable, use paragraphs.
2. Create comments for protected and public variables,methods and class.Give them meaningful names, if you do so then you may require less effort in description of your code.
3. The first sentence of each documentation comment is a summary sentence (crisp and informative).It contains a concise but complete description of the API item.
4. Why a method exists and what it does, this should be documented.Ask any programmer who has to maintain a code with real poor documentation. If you cannot document then do not code and forget about executing it.
5. Use 3rd person (descriptive) instead of 2nd person (prescriptive) in the documentation comments.
6. While describing a method or a class or an object created from the current class, describe it as given in example: Gets first name of the employee. Instead saying 'This method....'
7. Never use JAVADOC style comments inside methods.
8. All checked exceptions should be documented with the @throws tag.
9. C++ style (// ..) comments should be used for briefly describing a particular statement (preferably place the comment at the end of the statement, in the same line).
10. Take full advantage of JAVADOC and HTML tags to significantly improve the readability at HTML levels. Here are some of the HTML tags you can use –

• <UL> This is a bulleted list<li>a bullet point</li></UL>
• <CODE> …</CODE>- Anything that is Java code should be in code tags. E.g java keywords, package names, class names, method names
• <B> - boldify
• <i> - italicize

Each method comments should include

Purpose of the method
Examples of usage
@param based description of all input parameters
@return based description of the returned value
@throws based description of all the exceptions
@link or @see based reference to all the referred methods