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.7  Indicating functional group

Functions tend to literally come in functional groups. Thus, for example, there may be a number of routines which may be called which are defined in a screen management subsystem. It is useful to make the grouping of these functions easily identifiable, such that when a reader comes across a call to that functional area, it is immediately clear. This can be done by adding a prefix to names to identify their functional group:

SM_ReadField(), SM_CreateWindow()

There is a variety of conventions that can be used for these prefixes. You can use capitals, lower case or a mixture. You can use underscores or not. You can use one, two or more letters. You can use the first letters of the group name or you can use other letters.

SM_ReadField(), SMReadField(), smReadField(), Scr_ReadField()

Note that this prefix can be used as a part of the verb-noun combination (although it is now noun-verb) for describing the function, although this requires that the reader clearly understands the prefix.

Scr_Clear(), Kbd_Read(), fopen()

This naming system may be applied to all external interfaces into a given subsystem. It could be used internally too, although this is not so useful (although if the subsystem is composed of smaller subsystems, then it could apply here).

These rules may equally be applied to any other items in the subsystem, such as global variables, #define's and typedef's.

The functional prefix may be clearly identified if it differs in some way from the rest of the name. Thus, for example, if normal naming does not use underscores, then underscores may be used to separate out the functional prefix:

typedef struct
{
    unsigned int    XPos;
    unsigned int    YPos;
} SM_CURSOR;

struct SM_CURSOR   SM_MainCursor;

This naming convention guarantees, even in a large system, and even if it is being developed at different sites, that unique public symbols can be defined. A further advantage is that it makes the symbols easier to find in a compiler or linker symbol map, as they will all be grouped together.

The disadvantage with this system is that it increases the length of the symbol name, possibly without adding to the understanding of what the function actually does. It can also reduce their audible readability.

If this system is to be adopted, then the method of prefixing should be defined, and a list of standard prefixes and their meaning should be kept.