TOPIC 9.1.1
Coding Standards
Naming Data
This material is excerpted from Code Complete and
is copyright © 1996 by Steven C. McConnell. All Rights Reserved.
It may be reproduced and redistributed without charge as long as
it is unchanged and this copyright notice is included.
General Naming Considerations
- Does the name fully and accurately describe what the
variable represents?
- Does the name refer to the real-world problem rather than
the programming-language solution?
- Is the name long enough so that you don't have to figure
it out?
- Are qualifiers, if any, at the end of the name?
- Does the name use Count or Index instead
of Num?
Naming Specific Kinds of Data
- Are loop index names meaningful (something other than i,
j, or k if the loop is more than one or two lines long or
the loop is nested)?
- Have all "temporary" variables been renamed to
something more meaningful?
- Are boolean variables named so that their meaning when
they're True is clear?
- Do enumerated-type names include a base that indicates
the kind of the type, e.g. Color for ColorRed,
ColorGreen, etc.?
- Are named constants named for the abstract entity they
represent rather than the number they refer to?
- Naming Conventions
- Does the convention distinguish between local, module,
and global data?
- Does the convention distinguish between type names,
enumerated types, named constants, and variables?
- Does the convention identify input-only parameters to
routines in languages that don't enforce them?
- Is the convention compatible with standard conventions
for the language as much as possible?
- Are names formatted for readability?
Short Names
- Does the code use long names unless it's necessary to use
short ones?
- Does the code avoid abbreviations that save only one
character?
- Are all words abbreviated consistently?
- Are abbreviations limited to standard abbreviations?
- Are names pronounceable?
Are names that could be mispronounced avoided?
- Are short names documented with translation tables?
Common Naming Problems: Have You Avoided ...
- ... Names that are misleading?
- ... Names with similar meanings?
- ... Names that are different in only one or two
characters?
- ... Names that sound similar?
- ... Names that use numerals?
- ... Intentionally misspelling a name to make it shorter?
- ... Names that are commonly misspelled in English?
- ... Names the conflict with standard library routines or
pre-defined variables?
- ... Totally unrelated names?
- ... Hard-to-read characters?