Java Notes

Identifier Names

Getting the names of things right is extremely important. It makes a huge difference in readability. Many IDEs support refactoring, and specifically renaming. I will sometimes rename classes several times before I hit on exactly the obvious name. It's worth the effort.

Legal Characters

Every name is made from the following characters, starting with a letter:

No names can be the same as a Java keyword (eg, import, if, ...).

Examples

apple This is a legal name. Lowercase implies it's a variable or method.
Apple This is a different legal name. Uppercase implies it's a class or interface.
APPLE Yet a different legal name. All uppercase implies it's a constant.
topleft Legal, but multiple words should be camelcase.
top_left   Better, but camelcase is preferred to _ in Java.
topLeft Good Java style
top left ILLEGAL - no blanks in a name
import ILLEGAL - same as the Java keyword

Using Uppercase, Lowercase, and "Camelcase" Letters

The conventions for the use of upper- and lowercase is not enforced by compilers, but it is so widely observed, that it should have been. Camelcase is the practice of capitalizing the first letter of successive words in multi-word identifiers. Camelcase is much preferred in the Java community over the use of underscores to separate words, or even worse, no distinction made at word boundaries.

Class and interface names - Start with uppercase
Class and interface names start with an uppercase letter, and continue in lowercase. For multiple words, use camelcase. Eg, Direction, LogicalLayout, DebugGapSpacer.
Variable and method names - Lowercase
Lowercase is used for variable and method names. If a name has multiple words, use camelcase. Eg, top, width, topLeft, roomWidth, incomeAfterTaxes.
Constants - All uppercase, use _ to separate words
The names of constants (typically declared static final) should be in all uppercase. For example, BorderLayout.NORTH. When constant names are made from multiple words, use an underscore to separate words, eg, JFrame.EXIT_ON_CLOSE

Readable names are more important than most comments

Java doesn't care if your names are readable, but it's really important to make your names readable to humans.

I once worked on a project where we had to distribute the source code so that it could be compiled on another machine, but we didn't want to reveal our algorithms. We deleted all comments and indentation, and wrote a small program to change all variable names to combinations of "I", "1", "O", and "0", figuring that it would be too much effort for them to decode it. For example, the semi-readable

LogicalGapInfo topBorder = m_logicalLayout.getGapInfo(LogicalLayout.AXIS_V, 0);

Could be translated into

I001O I00I0 = O1001.OI001(O1OOI.IO010, 0);