# 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:

- Letters: a-z, A-Z, and other alphabetic characters from other languages.
- Digits: 0-9
- Special: _ (underscore)

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);