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.10  Naming replacement items

Replacement items are those which cause replacement by the compiler, i.e. #define's, typedef's, structure identifiers and enumerated items.

It is already a de facto standard to use only uppercase letters and underscores to name constants. This scheme may be continued to other replacement items as it clearly says, "this is effectively replaced with something else."

5.10.1  Constants

#define'd items typically contain limits or specific values for variables. Limits tend to be maxima or minima, which may be noted with simple suffixes or prefixes. Suffixes are probably more common, although the prefix reads more naturally:

WIND_SPEED_MAX    ...or...     MAX_WIND_SPEED

Specific values for variables will normally be nouns which are chosen to make the code more readable:

int     ScreenColor;
...
#define BLACK   1
#define WHITE   2
...
ScreenColor = BLACK;

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

If these might cause conflict or confusion, then an identifying prefix may be used:

#define SC_BLACK     1
#define SC_WHITE     2

5.10.2  Macros

Kernighan and Ritchie do not use capitals for macros:

#define max(A, B)   ((A) > (B)) ? (A) : (B))

It is, however, a good idea to make these distinguishable, as macros are notorious for causing obscure problems (see 8.12). Capitals are a useful reminder to the programmer that this is a replacement, not a function call:

#define MAX(A, B)   ((A) > (B)) ? (A) : (B))

If capitals are disliked, an alternative is to use a distinguishing prefix. e.g.  m_max.

Occasionally, it is better not to use capitals, such as where the macro is replacing a function (using capitals would require that all calls to the function be changed!).

Macros perform actions in the same way as functions, thus the same verb-noun naming convention may be used to name them.

5.10.3  'typedef's

typedef's describe types which define 'things' or attributes of things. Consequently, a similar naming scheme to variables may be used. Using capitals sticks to the 'replacement item' rule. It also allows variables to have the same name as the type. This could cause confusion (see 5.5.1) although as it is typedef and variable that have similar names (not two variables) it may be acceptable:

typedef struct
{
    int     XPosn;
    int     YPosn;
} CURSOR;
...
CURSOR  Cursor;

5.10.4  Structure tags

Structure and union tags are identical in use to typedef's, and thus follow the same rules:

struct CURSOR
{
    unsigned int    XPosn;
    unsigned int    YPosn;
};
...
struct CURSOR   MouseCursor;

There is less of a case for using capitals for typedef's and structure tags, as they are less likely to cause confusion. However, it is being consistent to use the same naming scheme for all replacement items.

5.10.5  Enumerated items

Enumerated items are newer facility available in C. They are an effective replacement for #define's, and will thus use similar naming rules. The enumeration tag will use the same naming rules as the similar structure tag:

enum    WEEKDAYS {MON, TUE, WED, THU, FRI};

<--Prev page | Next page -->