Comments provide information
helpful to
understanding and using your program. There are two kinds of
comments: implementation
comments and documentation
comments.
Implementation comments are used to describe a particular implementation.
Use implementation comments to provide overviews or summaries of chunks of code and to provide additional information that is not readily available in the code itself.
Comment the details of nontrivial or non-obvious design decisions; avoid comments that merely duplicate information that is clear from reading the code.Avoid over-commenting your code. A high frequency
of
comments sometimes reflects poor choices for identifier names.
Doc comments are meant to describe the specification of the code,
from
an implementation-free perspective, to be read by developers who might
not necessarily have the source code at hand.
Use javadoc comments to
provide developers with the information they need to use your program
or
class in their own code.