Java Reference
In-Depth Information
Guidelines for comments
Use
/
** *
/
documentation style comments
for comments that are useful in
code, and in automatically generated documentation (JavaDoc).
Use
/
* *
/
c-style comments
to block a piece of code from executing, or to
document a long description or algorithm.
Use
//
end-of-line comments
to drop in annotations at the end of a line,
or to drop in short comments between lines.
Keep a change history in the header of each method, or choose a
change control system that maintains an inline change history for you.
Guidelines for visibility
Use
private visibility
for attributes and methods that compute interme-
diate results important only to another calculation, and methods that
should be restricted to the defining class for safety or security.
Use
protected visibility
for attributes and methods that might be
required for future subclasses. In general, protected should be preferred
to private.
Use
public visibility
for methods that
must
be exposed to fulfill the con-
tract for the interface.
Use unspecified, or package, visibility for coordinated frameworks
within a single package. For example, a collection class utility set could
use this visibility to ensure that iterators could see other collection types.
Do not use
public visibility
for attributes.
Guidelines for design
Classes should be nouns. Watch words like
process
and
manager
that try
to short-circuit this rule.
Methods should be single actions.
Methods should be short and easy to understand.
Choose the simplest approach that will work.
Interfaces should generally be preferred over abstract classes: when an
implementation
might change
; to describe add-on features; when no
default implementation is specified.
Abstract classes should be used over interfaces when partial implementa-
tions are specified.
