StyleFile: Identifiers

General advice

Programs are full of named entities: variables, methods and classes to name but three. A good naming convention is therefore one of the most important contributors to program quality. Names of things in programs are referred to as identifiers. We begin with some general advice about identifiers.

Identifiers for classes

Use one or more words, all in lowercase except for their initial letters, e.g. BankAccount.

Class definitions define sets of objects, so nouns are usually the more appropriate identifiers, e.g. Color, BankAccount, PersonName, Ball, Point.

Identifiers for methods

The same advice applies to both instance methods and class methods.

Use one or more words, all in lowercase except for any inner initials, e.g. setSize, getUserChoice.

The first word should generally be a verb (an action, such as add/remove, insert/delete, increment/decrement, lock/unlock, open/close, create/destroy, get/set, show/hide, start/stop or verbs from the problem domain such as credit, debit, deposit, withdraw, etc.).

OK, so the first word in the method identifier is a verb. If there are subsequent words, they might be nouns that qualify the action, e.g. they might say what gets changed (setSize) or what gets returned (getCurrentBalance).

An instance method identifier needn't state what class of object it applies to. For example, moveBall is no better than move since, when we send a message, we will know what object we are sending it to (as long as that is well-named!), e.g. redBall.move(10) is probably clearer than redBall.moveBall(10).

Where a method returns a boolean and so tells you something about the state an object is in, choose your method identifier so that messages read like sentences that are true or false. For example, if you use identifiers such as isOverdrawn, equals, isGreaterThan, then in messages we get such things as:

if (myAccount.isOverdrawn())

and

while (stack.isEmpty())

Remember, where a method returns a boolean, you can just write

if (myAccount.isOverdrawn())

you do not have to write

if (myAccount.isOverdrawn() == true)

Identifiers for variables (general advice)

There are four kinds of variable in Java: formal parameters, local variables, instance variables and class variables. Each is treated separately below.

In fact, we can distinguish another subcategory. Class variables (ones that are designated static) can be split into: those that are also final, and those that are not. We refer to final class variables (static final) as named constants, and they deserve a separate treatment below.

Before we give the separate treatments, we summarise some general advice.

With only one exception, when you are writing variable identifiers, use one or more words, all in lowercase except for any inner initials, e.g. currentBalance.

The exception is named constants. The convention is to write these all in uppercase, using underscores to separate words within the identifier, e.g. HOURS_PER_DAY.

Variable identifiers will generally be nouns. An exception is those whose type is boolean, which ought to have identifiers that suggest two states and can begin with a verb so that uses of these variables read like sentences that are true or false, e.g.

if (this.isReady)

Identifiers for formal parameters

Use one or more words, all in lowercase except for any inner initials, e.g. theOpeningBalance.

There is a temptation to use very short identifiers such as x and y. Only if parameters are very generic should this be done, e.g. public double squareRoot(double x) is probably OK. In all other cases, identifiers should be long enough to be meaningful.

My own preference is for most formal parameter identifiers to begin with one of the words the, a or an, e.g. anAge.

In constructors and setters, it is acceptable to use identifiers that are the same as those of the corresponding instance variables. I tend not to do this. If you choose to do it, remember that in no other case should a formal parameter identifier eclipse some other identifier in the same class definition.

Within a method body, avoid, if you can, assigning new value into parameters. If you do assign a value into a parameter, it is hard to choose a formal parameter identifier that accurately describes both what the formal parameter contained when the method was invoked and what the parameter contains once it has been re-assigned.

Identifiers for local variables

Use one or more words, all in lowercase except for any inner initials, e.g. positionOfSpace.

There is a temptation to use short identifiers, even as short as x and i. A good example is the counter in a for loop. This may be acceptable when the variable has very limited scope (as in the case of a for loop counter). But, when the scope of a local variable extends over any substantial part of a method body, then the variable ought to be given a more meaningful identifier. (And, even with for loop counters, you should ask yourself whether there is a meaningful identifier you could use in place of i. By the way, index, counter or abbreviations of these are generally not any better than just using i!)

Local variables are temporary working variables. That's the whole point of them. It therefore gives your reader zero information if the identifier you choose is temp or tmp! Choose something more meaningful. (A well-accepted exception is when you are swapping elements, e.g. when sorting an array. Then, use of temp is common and therefore clear.)

Identifiers for instance variables

Use one or more words, all in lowercase except for any inner initials, e.g. currentBalance.

Meaningful nouns are essential.

I see no reason to include the class identifier as part of an instance variable identifier. E.g. in an Employee class, the variables can be name, age, etc.; we don't need to use empName, empAge. The encapsulation provided by class definitions make the extra word unnecessary.

Identifiers for class variables

The usual Java convention is to distinguish static final variables (i.e. named constants) from other static variables. Named constants are treated separately below.

In the case of class variables (static) that are not named constants (not final), use one or more words, all in lowercase except for any inner initials, e.g.

private static int nextBorrowerNum;

Identifiers for named constants

Use one or more words, all in uppercase, with the words separated by underscores, e.g.

public static final int SCREEN_WIDTH = 400;

Just because the value cannot be re-assigned within the program should not lead you to use identifiers such as TWENTY_FOUR. You should be choosing identifiers that are meaningful so that they improve readability. What's more, while a named constant cannot have its value re-assigned within the program, it is often the case that, at some point, the programmer will want to edit the program and change the value. This issue is discussed in more detail in StyleFile: Variables and constants.

Identifiers for constructors, files & packages

Constructors: We have no choice over their identifiers; their identifiers must be the same as the class identifier.

Program file names: We have no choice again; they must be the same as the class identifier plus the suffix .java (Here I am assuming there is only one class definition per file, which is generally thought to be good practice. If there's more than one class definition in a file, only one is allowed to be public, and this is the one that the file must be named after.)

Package names: These correspond to directory names, and a convention would be to use all lowercase in order to sidestep issues concerning those operating systems that are or are not case-sensitive. Another part of the naming convention is to use an Internet domain name in reverse as the first part of the package name, e.g. ie.ucc.cs