The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 5 : Naming

PART 2 : COMMENTING AND NAMING

CHAPTER 5 : Naming
5.1 Constraints upon naming
5.2 Abbreviations
5.3 Short names
5.4 Separating words
5.5 Spelling of names
5.6 Naming functions
5.7 Indicating functional group
5.8 Naming variables
5.9 Indicating type
5.10 Naming replacement items
5.11 Naming Files and Directories
5.12 Summary

<--Prev page | Next page -->

5.1  Constraints upon naming

C names are constrained by the value and number of characters that they can use. Given these language constraints, the way that they are used must also be constrained by the standard to optimize the legibility of the name and the code.

5.1.1  Character constraints

C identifier names can use all letters (a..z, A..Z), all numbers (0..9) and the underscore (_). This includes separate recognition of upper and lower case letters. Thus the names 'WindSpeed', 'windspeed' and 'WINDSPEED' are all different - a fact that we can use in creating names.

5.1.2  Name length constraints

The original C language definition limited the significant number of letters in a name to 8 (or sometimes less!) characters. Thus, to many compilers, names such as 'ClearParaStatus' and 'ClearPark' are in fact the same name, 'ClearPar'! In programs of any size, this limitation is woefully inadequate, and complex systems of using unique prefixes may become necessary to ensure portability, eg. 'RGDD03_ClearPark'.

Fortunately, ANSI C allows 31 significant characters, which is a far more practical limit (you should never need a name this long!), and most modern compilers allow at least this number of characters.

Note that there can be different constraints upon internal and external symbols, and although compilers may be able to cope with longer names, some linkers limit the size of external symbols to as little as six characters, and may even be case-insensitive. This is particularly inconvenient, as external names are most important to keep unique and readable. A workaround to this is to redefine external names:

#define   ClearParaStatus RGDD04
int  ClearParaStatus;

Unless it is really necessary to be original-C compatible, it is worth ensuring that your compiler and linker allow long names, as the penalty of sticking to 8-character names is quite severe. You must also, of course, be able to assure that future maintainers of your program will also be able to use this name length.

5.1.3  Legibility constraints

There is a dilemma in defining the name of a variable. You can make it really clear what the variable means by using a sentence about it. However, although this may improve the readability of the name, it can actually harm the readability of the code. When using long names, the code rapidly tramps across towards the right hand margin, causing cramps and wraps:

CurrentWordEnhancementCode = StandardWordEnhancementCodes[CurrentWordIndex]
                                + StandardWordCodeOffset
                                - WordEnhancementCorrection;

---------------------------------------------------------------------------

There is, somewhere between the meaningless abbreviation and the sentence-name, a balance where the meaning of the name is clear, yet it is easy and not unwieldy to use. Careful thought, functional prefixes (see 5.7) and standard abbreviations (see 5.2) can all help. Thus the example above could be shortened to:

WdEnhCode = WC_Enhance[CurrWd] + WC_Offset - WdEnhCorrn;

As an approximation, there are breakpoints in legibility about every 5 characters. It is seldom easy to devise names less than 5 characters which have any real meaning. It is usually not too difficult to devise names around 10 characters long which are reasonably descriptive. Increasing the length to around 15 or 20 characters long can added meaning or include more words:

5 characters:            WdEnh

9 characters:            WdEnhCode

11 characters:          WordEnhCode

12 characters:          WdEnhanceCode

15 characters:          WordEnhanceCode

19 characters:          WordEnhancementCode

As a practical limit for name length, around 15 characters is a reasonable guideline.

Note that you can still get a rather long name when using structures and pointers:

Paragraph->Line.Enhancement.UnderlineStatus

As a general rule, the minimum name length should be proportional to the scope of the item they describe. Thus a local variable in a short function may be quite short, whilst a public function name would usually be somewhat longer.

<--Prev page | Next page -->