I just love Steve McConnell's classic book Code Complete 2, and I recommend it to everyone in the Software 'world' who's willing to progress and sharpen his skills.
Other blog posts in this series:
- Part 1 (Chapters 1 - 4): Laying the Foundation
- Chapter 5: Design in Construction
- Chapter 6: Working Classes
- Chapter 7: High-Quality Routines
- Chapter 8: Defensive programming
- Chapter 9: Pseudocode Programming Process
- Chapter 10: General Issues in Using Variables
The Most Important Naming Consideration
The name must fully and accurately describe the entity that the variable represents. Names should be as specific as possible. Names like
i that are general enough to be used for more than one purpose are not as informative as they could be and are usually bad names.
Variable names should be 10 to 16 characters long.
Computed-Value Qualifiers in Variable Names
Many programs have variables that contain computed values:
maximums, and so on. If you modify a name with a qualifier, put the modifier at the end of the name. Try to avoid using
num, instead use
customerCount for total numbers of customers and
customerIndex refers to a specific customer.
By establishing this convention, you avoid the confusion you might create if you were to use both
revenueTotal in the same program.
Naming Status Variables
Think of a better name than
flag for status variables.
Here are some examples of flags with bad names:
if ( flag ) ... if ( printFlag == 16) ... if ( statusFlag & 0x0F) ...
statusFlag = 0x80 give you no clue about what the code does unless you wrote the code or have a documentation. Here are equivalent code examples that are clearer:
if ( dataReady ) ... if ( reportType == ReportType_Annual ) ... if ( characterType & PRINTABLE_CHAR ) ...
characterType = CONTROL_CHARACTER is more meaningful than
statusFlag = 0x80.
Naming Temporary Variables
They're usually called
x, or some other vague and non-descriptive name. In general, temporary variables are a sign that the programmer does not yet fully understand the problem. Moreover, because the variables are officially given a "temporary" status, programmers tend to treat them more casually than other variables, increasing the chance of errors.
Naming Boolean Variables
- Keep typical boolean names in mind:
- success or ok - if you can, replace success with a more specific name that describes precisely what it means to be successful
- Give boolean variables names that imply true or false
- Names like
sourceFileare poor boolean names because they're not obviously true or false. What does it mean if
statusis true? For a better result, replace
statuswith a name like
- Names like
- Use positive boolean variable names - negative names like
notDoneare difficult to read when they are negated
When naming constants, name the abstract entity the constant represents rather than the number the constant refers to.
FIVE is a bad name for a constant (regardless of whether the value it represents is 5.0).
CYCLES_NEEDED is a good name.
The key is that any convention at all is often better than no convention.
Guidelines for a Language-Independent Convention
jare integer indexes.
first- The first element that needs to be dealt with in an array.
g- Global variable.
i- Index into an array.
last- The last element that needs to be dealt with in an array.
lim- The upper limit of elements that need to be dealt with in an array. Generally,
last + 1.
m- Class-level variable
max- The absolute last element in an array or another kind of list.
maxrefers to the array itself rather than to operations on the array
min- The absolute first element in an array or another kind of list.
Advantage of standardized prefixes - they give you all the general advantages of having a naming convention as well as several other advantages. Because so many names are standard, you have fewer names to remember in any single program or class.
Kinds of Names to Avoid
- Avoid names with similar meanings. For example,
- Avoid numerals in names. E.g.
file2. You can almost always think of a better way to differentiate between two variables than by adding a 1 or 2 onto the end of the name.
- Avoid words that are commonly misspelled in English:
recieptand so on...