Programming Style - Multimedia Introduction to Programming Using Java - page 362

If you decide to change what the implementation of a statement-comment doe:,

3b . Change the statement-comment, then the implementation.

Concerning variables and their meanings:

3c. Change a variable definition, then statements that use it.

Obviously, documentation that is inconsistent with the program is sure to
lead to bugs. Following these guidelines will help reduce the bugs in your pro-
gram and thus the time spent debugging.

13.1 Naming conventions

We describe guidelines and conventions for naming variables, methods, classes,
and packages.

13.1.1 Conventions for variable names

Some people will tell you to make variable names long and mnemonic in order
to encapsulate what the variable means in the name itself. Others will tell you to
use short names, like x and p1 because they make a program look shorter and
manageable. There is a tension between using meaningful names and keeping
names short. The best way to solve the dilemma is to use different rules for dif-
ferent situations. Java has four kinds of variable: (1) parameter, (2) local vari-
able, (3) instance variable (or field), and (4) class variable (or static variable),
and using a different, well-thought-out convention for each one makes sense.

Lesson page
13-2

General Guidelines
Here are some general guidelines to be followed for variable names:

1. A variable name should consist of small letters, except that all “words” with-
in it (except the first) should be capitalized. In Java, this convention is almost
universally used. Here are some variable names that follow this convention:

x numberOfDogs footSize yCoordinate
2. Do not use a long mnemonic name as a substitute for a careful definition of a
variable in a comment; names rarely convey the complete meaning of the entity
that they name.

3. Make the length of a variable name proportional to the size of its scope. Local
variables have the smallest scope, then parameters, then instance and static vari-
ables.

With these general guidelines, we now turn to more detailed ones.