Tuesday, November 11, 2008

Comment Type of Java

Documentation
Usage -- Use documentation comments immediately before declarations of interfaces, classes, member functions and fields to document them.
Documentation comments are processed by javadoc, see below, to create external documentation for a class.
Example --

/**
Customer - A customer is any person or organization that we sell services and products to.
@author S.W.Ambler
*/

-----

C style
Usage -- Use C-style comments to document out lines of code that are no longer applicable, but that you want to keep just in case your users change their minds, or because you want to temporarily turn it off while debugging.
Example --

/*
This code was commented out by J.T.Kirk on Dec 9, 1997 because it was replaced by the preceding code. Delete it after two years if it is still not applicable.

...(the source code)
*/

----
Single line
Usage -- Use single line comments internally within member functions to document business logic, sections of code, and declarations of temporary variables.
Example --

// Apply a 5% discount to all invoices
// over $1000 as defined by the Sarek
// generosity campaign started in
// Feb.of 1995.



The author of JavaCodingStardards perfer using sigle-line comments for business logic and C-style comments for documenting out old code. His another advice is to not waste time aligning endline comments.

No comments: