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.
If this is the problem, then do not persist with your current design. Do not give the entity a convoluted, vague or inaccurate identifier. Instead, re-design your program.
currentSize
when it holds the previous
size of some structure, or where it holds
the current size plus one, is bad practice.
This sounds obvious but it is quite common for programmers to use, for example, inaccurate local variable identifiers. (The local variable may, for example, be used to accumulate some result over the course of several lines of a method. But its identifier might describe only what the variable contains initially or ultimately.)
EmployeeData
is typically better than
InputRecord
.
In particular, you should generally avoid identifiers
that indicate how the data is represented, e.g. EmployeeArray
is not as good as SetOfEmployees
. There are two reasons
for this:
(There are exceptions to this convention. Firstly, sometimes we are
writing code for generic Computer Science data structures, in which case
implementational identifiers such as node
, nextCell
, etc.
may be
used. Secondly, in weakly typed languages, it may be a good idea
to include some indication of the type in an identifier.
Only the first of these two
exceptions applies to Java.)
Long identifiers are easily misspelled and mistyped, but at least the compiler is likely to spot your mistakes.
A short identifier,
such as indx
is easily mistyped as idx
,
which may be another variable in the program: the compiler is less
likely to find these kinds of collisions.
StudNum
(student exam number) and
NumStud
(the total number of students); EmployeeRec
(employee record) and EmployeeRep
(employee report);file1
and file2
(give them identifiers that express
their meaning, e.g. sourceFile
and targetFile
);nameString
, namestring
and name_string
(these are too easily confused);string
(too close to the name of a class in the
standard Java library);
True
(too close to
a Java reserved word);flag0
and flagO
(one of these uses
zero, the other uses capital letter O).
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
.
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.).
calculate
or
compute
.
In a program, some data is stored; other data is computed. But this is a very changeable aspect of a program. This may lead you to regret your choice of identifier.
Consider, for example, a program that
stores centigrade
temperatures and uses these to compute Fahrenheit temperatures.
You might write a method called
retrieveCentigrade
and another called computeFahrenheit
.
These method identifiers reveal the fact that centigrade temperatures
are stored, whereas Fahrenheit ones are computed.
If, at a later point, you decide to revise the program so that it stores Fahrenheit temperatures and computes centigrade ones, or so that it stores both, then you really need to change the method identifiers. (And, if you do not, your identifiers will now be misleading.)
If, instead, you had, from the outset,
chosen identifiers that were more neutral, e.g.
getCentigrade
and getFahrenheit
, then
changes to what was stored/computed would not require changes to
the identifiers.
Programmers writing client code might also find it more convenient and memorable if all your getters have identifiers that begin with 'get', rather than having a mix (get/compute/retrieve/fetch/calculate).
handle
,
process
, perform
, dealWith
and do
:
they tell the reader nothing.
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)
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)
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.
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.)
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.
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;
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.
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