Structure and Documentation
(in 
Draft Java Coding Standard, by 
Doug Lea)
Naming conventions
(in Draft Java Coding Standard, by Doug Lea)
Recommendations
(in Draft Java Coding Standard, by Doug Lea)
Packages
(in Draft Java Coding Standard - Structure and Documentation, by Doug Lea)
Program Files
(in Draft Java Coding Standard - Structure and Documentation, by Doug Lea)
Classes and Interfaces
(in Draft Java Coding Standard - Structure and Documentation, by Doug Lea)
Class Variables
(in Draft Java Coding Standard - Structure and Documentation, by Doug Lea)
Methods
(in Draft Java Coding Standard - Structure and Documentation, by Doug Lea)
Local declarations, statements, and expressions
(in Draft Java Coding Standard - Structure and Documentation, by Doug Lea)
Naming Conventions: packages
lowercase. Consider using the recommended domain-based conventions described in the
Java Language Specification, page 107 as prefixes.
(For example, edu.oswego.cs.dl.)
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: files
The java compiler enforces the convention that file names have the same base name as the public class they define.
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: classes:
CapitalizedWithInternalWordsAlsoCapitalized
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: Exception class:
ClassNameEndsWithException.
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: Interface. When necessary to distinguish from similarly
named classes:
InterfaceNameEndsWithIfc.
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: Class. When necessary to distinguish from similarly
named interfaces:
ClassNameEndsWithImpl or
ClassNameEndsWithObject
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: constants (finals):
UPPER_CASE_WITH_UNDERSCORES
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: private or protected:
trailingUnderscore_
(Yes, this is ugly. It is good that it is ugly!)
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: static private or protected:
twoTrailingUnderscores__
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: local variables
lower_case_with_underscores
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: methods:
firstWordLowerCaseButInternalWordsCapitalized()
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: factory method for objects of type X:
newX
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: converter method that returns objects of type X:
toX
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: method that reports an attribute x of type X:
X x() or X getX().
(in
Draft Java Coding Standard, by Doug Lea)
Naming Conventions: method that changes an attribute x of type X:
void x(X value) or void setX(X value).
(in
Draft Java Coding Standard, by Doug Lea)
Minimize * forms of import. Be precise
about what you are importing. Check that all declared imports
are actually used.
(in Draft Java Coding Standard, by Doug Lea)
When sensible, consider writing a main for the principal class
in each program file. The main should provide a
simple unit test or demo.
(in Draft Java Coding Standard, by Doug Lea)
For self-standing application programs, the class with main
should be separate from those containing normal classes.
(in Draft Java Coding Standard, by Doug Lea)
Consider writing template files for the most common kinds of
class files you create: Applets, library classes, application classes.
(in Draft Java Coding Standard, by Doug Lea)
If you can conceive of someone else implementing a class's
functionality differently, define an interface, not an abstract
class. Generally, use abstract classes only when they are
``partially abstract''; i.e., they implement some functionality
that must be shared across all subclasses.
(in Draft Java Coding Standard, by Doug Lea)
Consider whether any class should implement Cloneable
and/or Serializable.
(in Draft Java Coding Standard, by Doug Lea)
Declare a class as final only if it is a subclass or
implementation of a class or interface declaring all of its
non-implementation-specific methods. (And similarly for
final methods).
(in Draft Java Coding Standard, by Doug Lea)
Never declare instance variables as public.
(in Draft Java Coding Standard, by Doug Lea)
Minimize reliance on implicit initializers for instance variables
(such as the fact that reference variables are initialized to
null).
(in Draft Java Coding Standard, by Doug Lea)
Minimize statics (except for static final constants).
(in Draft Java Coding Standard, by Doug Lea)
Generally prefer long to int,
and double to float. But use
int for compatibility with standard Java constructs
and classes (for the major example, array indexing, and all of
the things this implies, for example about maximum sizes of
arrays, etc).
(in Draft Java Coding Standard, by Doug Lea)
Use final and/or comment conventions to indicate
whether instance variables
that never have their values
changed after construction are intended to be constant (immutable)
for the lifetime of the object (versus those that just so
happen not to get assigned in a class, but could in a subclass).
(in Draft Java Coding Standard, by Doug Lea)
Generally prefer protected to private.
(in Draft Java Coding Standard, by Doug Lea)
Avoid unnecessary instance variable access and update methods.
Write get/set-style methods only when they are
intrinsic aspects of functionality.
(in Draft Java Coding Standard, by Doug Lea)
Minimize direct internal access to instance variables inside methods.
Use protected access and update methods instead (or
sometimes public ones if they exist anyway).
(in Draft Java Coding Standard, by Doug Lea)
Avoid giving a variable the same name as one in a superclass.
(in Draft Java Coding Standard, by Doug Lea)
Prefer declaring arrays as Type[] arrayName
rather than Type arrayName[].
(in Draft Java Coding Standard, by Doug Lea)
Ensure that non-private statics have sensible values even if no instances
are ever created. (Similarly ensure that static methods
can be executed sensibly.) Use static intitializers (static { ... }
) if necessary.
(in Draft Java Coding Standard, by Doug Lea)
Write methods that only do ``one thing''. In particular,
separate out methods that change object state from those that
just rely upon it. For a classic example in a
Stack, prefer having two methods Object
top() and void removeTop() versus the single
method Object pop() that does both.
(in Draft Java Coding Standard, by Doug Lea)
Define return types as void unless they return
results that are not (easily) accessible otherwise. (i.e.,
hardly ever write ``return this'').
(in Draft Java Coding Standard, by Doug Lea)
Avoid overloading methods on argument type. (Overriding on
arity is OK, as in having a one-argument version versus a two-argument
version). If you need to specialize behavior according
to the class of an argument, consider instead choosing
a general type for the
nominal argument type (often Object) and using
conditionals checking instanceof. Alternatives
include techniques such as double-dispatching, or often best,
reformulating methods (and/or those of their arguments)
to remove dependence on exact argument type.
(in Draft Java Coding Standard, by Doug Lea)
Declare all public methods as synchronized; or if not, describe the
assumed invocation context and/or rationale for lack of
synchronization.
(in Draft Java Coding Standard, by Doug Lea)
Prefer synchronized methods to synchronized
blocks.
(in Draft Java Coding Standard, by Doug Lea)
If you override Object.equals, also override Object.hashCode,
and vice-versa.
(in Draft Java Coding Standard, by Doug Lea)
Override readObject and WriteObject
if a Serializable class relies on any
state that could differ across processes, including, in
particular, hashCodes and transient fields.
(in Draft Java Coding Standard, by Doug Lea)
If you think that clone() may be called in a class
you write, then explicitly define it (and declare the class to
implement Cloneable).
(in Draft Java Coding Standard, by Doug Lea)
Always document the fact that a method invokes wait
(in Draft Java Coding Standard, by Doug Lea)
Whenever reasonable, define a default (no-argument) constructor
so objects can be created via Class.newInstance().
(in Draft Java Coding Standard, by Doug Lea)
Prefer abstract methods in base classes to those
with default no-op implementations. (Also, if there is a common
default implementation, consider instead writing it as a
protected method so that subclass authors can just
write a one-line implementation to call the default.)
(in Draft Java Coding Standard, by Doug Lea)
Use method equals instead of operator == when
comparing objects. In particular, do not use == to
compare Strings.
(in Draft Java Coding Standard, by Doug Lea)
Always embed wait statements in while
loops that re-wait if the condition being waited for does not
hold.
(in Draft Java Coding Standard, by Doug Lea)
Use notifyAll instead of notify or
resume.
(in Draft Java Coding Standard, by Doug Lea)
Declare a local variable only at that point in the code where
you know what its initial value should be.
(in Draft Java Coding Standard, by Doug Lea)
Declare and initialize a new local variable rather
than reusing (reassigning) an existing one whose value happens to
no longer be used at that program point.
(in Draft Java Coding Standard, by Doug Lea)
Assign null to any reference variable that is
no longer being used. (This includes, especially, elements
of arrays.)
(in Draft Java Coding Standard, by Doug Lea)
Avoid assignments (``='') inside if
and while conditions.
(in Draft Java Coding Standard, by Doug Lea)
Document cases where the return value of a called method
is ignored.
(in Draft Java Coding Standard, by Doug Lea)
Ensure that there is ultimately a catch for
all unchecked exceptions that can be dealt with.
(in Draft Java Coding Standard, by Doug Lea)
Embed casts in conditionals.
(in Draft Java Coding Standard, by Doug Lea)
Document fragile constructions used solely for the sake of
optimization. (in Draft Java Coding Standard, by Doug Lea)
Do not require 100% conformance to rules of thumb such as
the ones listed here! (in Draft Java Coding Standard, by Doug Lea)
The only time that you might want to not use accessors is when execution time is of the utmost
importance, however, it is a very rare case indeed that the increased coupling within your application
justifies this action. Lea ( 1996) (see Draft Java Coding Standard, by Doug Lea)
makes a case for minimizing the use of accessors on the grounds that it is
often the case that the values of attributes in combination must be consistent, and that it isn't wise to
provide access to attributes singly. He's right, so don't! I (Scott W. Ambler) think that Lea has missed the point that you
don't need to make all accessor methods public. When you are in the situation that the values of some
attributes depend upon one another then you should introduce methods that do the "right thing" and make
the appropriate accessor methods either protected or private as needed. You don't have to make all of
your accessors public.(quoted from 3.4 THE USE OF ACCESSOR METHODS 3.4.5 Why Shouldn't You Use Accessors? in AmbySoft Inc.
Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 20)
Always Initialize Static AttributesDoug Lea ( 1996) (see
Draft Java Coding Standard, by Doug Lea)
validly points out that you must ensure that static attributes, also known as class
attributes, be given valid values because you can't assume that instances of a class will be created before a
static attribute is accessed. Lea suggests the use of static initializers (Grand, 1997), static blocks of code
which are automatically run when a class is loaded. Note that this is a problem only if you choose not to
use accessor methods for static attributes – With accessor methods you can always use lazy initialization
to guarantee that the value of an attribute is set. The use of accessor methods to encapsulate attributes
gives you complete control over how the are used, while reducing coupling within your code. A win-win
situation.
(quoted from 3.5 ALWAYS INITIALIZE STATIC ATTRIBUTES in AmbySoft Inc.
Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 20/21)
The development/maintenance history of the class. It is common practice to include a history
table listing dates, authors, and summaries of changes made to a class (Lea, 1996). (see Draft Java Coding Standard, by Doug Lea)
The purpose of
this is to provide maintenance programmers insight into the modifications made to a class in the past,
as well as to document who has done what to a class.
(quoted from 6.1 STANDARDS FOR CLASSES 6.1.2 Documenting a Class in AmbySoft Inc.
Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 26/27)
Naming InterfacesThe Java convention is to name interfaces using mixed case with the first letter of each word capitalized. The preferred Java convention for the name of an interface is to use a descriptive adjective, such as Runnable or Cloneable, although descriptive nouns, such as Singleton or DataInput, are also common (Gosling, Joy, Steele, 1996).
Alternatives:
- Prefix the letter 'I' to the interface name. Coad and Mayfield (...)
- Postfix 'Ifc' onto the interface name. Lea ( 1996) suggests appending 'Ifc' to the end of an interface
name, resulting in names like SingletonIfc or RunnableIfc, whenever the name of an interface is
similar to that of a class (Lea, 1996). I like the general idea, although I would be tempted to
prefix the name with the full word 'Interface.' This suggestion suffers from the same problem as the one above.
(see
Draft Java Coding Standard, by Doug Lea)
(quoted from 6.2 STANDARDS FOR INTERFACES 6.2.1 Naming Interfaces in AmbySoft Inc.
Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 28)
Documenting a PackageYou should maintain one or more external documents that describe the purpose of the packages developed by your organization. For each package you should document:
- The rationale for the package. (...)
- The classes in the package. Include a list of the classes and interfaces in the package with a brief,
one-line description of each so that other developers know what the package contains.
Lea ( 1996) (see Draft Java Coding Standard, by Doug Lea)
suggests creating an HTML file called index.html for each package, putting the file into the
appropriate directory for the package. A better name would be the fully qualified name of the package,
postfixed with .html, so that you don't have to worry about accidentally overwriting one package
documentation file with another. I like Lea's idea, in general, but my (Scott W. Ambler) experience has shown that similarly
named files get overwritten often enough to modify his approach slightly.
Java Coding Standards by Scott W. Ambler, v. July 10, 1997, p. 30)
Documenting a Compilation UnitAlthough you should strive to have only one class or interface declaration per file, it sometimes makes sense to define several classes (or interfaces) in the same file. My general rule of thumb is that if the sole purpose of class B is to encapsulate functionality that is needed only by class A then it makes sense that class B appear in the same source code file as class A 8 . As a result, I've separated the following documentation conventions that apply to a source code file, and not specifically to a class:
- For files with several classes, list each class. If a file contains more than one class you should provide a list of the classes and a brief description for each (Lea, 1996).
- The file name and/or identifying information. The name of the file should be included at the top of it (Lea, 1996). The advantage is that if the code is printed you know what the source file for the code is.
- Copyright information. If applicable you should indicate any copyright information for the file (Lea, 1996). It is common to indicate the year of the copyright and the name of the individual/organization that holds the copyright. Note that the code author may not be the holder of the copyright.
Draft Java Coding Standard, by Doug Lea)
(quoted from 6.4 STANDARDS FOR COMPILATION UNITS 6.4.2 Documenting a Compilation Unit in AmbySoft Inc.
Java Coding Standards by Scott W. Ambler, v. July 10, 1997, pp. 30 & 31)