syque.com

The Psychology of Quality and More

| Menu | Books | Share | Search | Settings |

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.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:

 

struct
{
    int     PersonName;
    int     PersonAge;
} Person;
...
Person.PersonAge = AskAge();

 

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:

 

struct
{
    int     Name;
    int     Age;
} Person;
...
Person.Age = AskAge();

 

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):

 

struct
{
    int     PsnName;
    int     PsnAge;
} Person;

 

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'.

5.8.2  Booleans

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.

 

<--Prev page | Next page -->

 

Site Menu

| Home | Top | Settings |

Quality: | Quality Toolbook | Tools of the Trade | Improvement Encyclopedia | Quality Articles | Being Creative | Being Persuasive |

And: | C Style (Book) | Stories | Articles | Bookstore | My Photos | About | Contact |

Settings: | Computer layout | Mobile layout | Small font | Medium font | Large font | Translate |

 

You can buy books here

More Kindle books:

And the big
paperback book


Look inside

 

Please help and share:

 

| Home | Top | Menu |

© Changing Works 2002-
Massive Content -- Maximum Speed