How we change what others think, feel, believe and do
CHAPTER 5 : Naming
5.8 Naming variables
Variables are different to functions, in that they typically hold 'information'. This can be usually described with an abstract noun (an abstract noun describes something which is intangible):
Status, Speed, Count
What the 'status', 'speed' or 'count' is of is not clear here, but this type of name may be sufficient, particularly where the variable is used within a limited (both logical and physical) context. This must be where its meaning is quite clear, even to someone reading just a part of the program.
What the 'information' is about is usually some 'thing' more concrete which can usually be named by using another noun:
DoorStatus, WindSpeed, NodeCount
Complex situations can be addressed by using adjectives being used to further qualification the variable:
FrontDoorStatus, NorthWindSpeed, FreeNodeCount
Longer variable names can be more troublesome than long function names, as variables are used more often in expressions than functions, with the result that the expression tramps across the page, possibly wrapping onto the next line.
As with function names, a compromise between using long names to improve the understandability of the variables and using short names to improve the readability of the code, must be found, possibly using abbreviations (see 5.2).
There are some special cases of variable naming which may also be considered:
5.8.1 Naming Structures
If the above rules are used for structures, then some redundancy can occur:
Thus, although the structure members, 'PersonName' and 'PersonAge' follow the rules for creating variable names, the use of the noun, 'Person', is redundant, as it is used in both the structure name and the structure member name. This is because the structure member is not independent - it is inescapably a part of the structure. The naming rules should thus be applied to the whole structure.
The item to be named still follows the pattern for a variable, in that it is 'information' about a 'thing'. The difference between a variable and a structure is simply that the structure is the complex 'thing' with the structure members containing individual bits of 'information'. Thus the structure is named with a noun, and the members are named with abstract nouns:
Thus, if you are careful about both structure and member names, they can be combined to make most readable combinations.
There is a danger with this in large systems where different structures may use the same member name. This may be confusing, particularly where the structures are similar or where the members are passed as function parameters. Structure member names can be unique in ANSI, but not all compilers support this. In this case, it is better to revert to using the noun prefix on the structure members (possibly in abbreviated format):
There can also be a problem with nested structures or chains of pointers where a pointer is used to bypass the long chain. Thus where 'Widget.Package.Dimensions.Width' is a clear usage, if a pointer is connected directly to 'Width', then its name must carefully be chosen to retain clarity. e.g. 'DimPtr->Width' does not make it clear what the 'Width' is of. A better name would be something like 'WidgetPackage->Width'.
Although it is not a native C type, the boolean variable is extremely common. It is useful to name these variables such that they read naturally. Consider the difference between the following examples:
(a) if ( Door )
This tells little of what the door has done. It could be broken, open, closed or locked. More information is needed:
(b) if ( DoorOpen )
This is much better. The variable clearly flags whether the door is open or closed. However, there is another small addition we can make to improve the readability even further:
(c) if ( DoorIsOpen )
The little word 'is' helps solidify the intent of the variable. 'DoorOpen' could, for example, contain the number of the door which is open. With 'DoorIsOpen' there can be no mistake.
According to the context, other verbs can be used to improve the subtlety of meaning. 'DoorIsOpen' given no indication of when the door was opened (if it was ever shut). 'DoorHasOpened', however, implies that it was opened recently, and 'DoorWasOpen' suggests that it has been open sometime in the past, although it is may now be shut.
And the big