Routines created with preprocessor macros call for a few unique considerations. The following rules and examples pertain to using the preprocessor in C++. If you're using a different language or preprocessor, adapt the rules to your situation.

Fully parenthesize macro expressions. Because macros and their arguments are expanded into code, be careful that they expand the way you want them to. One common problem lies in creating a macro like this one:

#define Cube( a ) a*a*a

If you pass this macro nonatomic values for a, it won't do the multiplication properly. If you use the expression Cube( x+1 ), it expands to x+1 * x + 1 * x + 1, which, because of the precedence of the multiplication and addition operators, is not what you want. A better, but still not perfect, version of the macro looks like this:

#define Cube( a ) (a)*(a)*(a)

This is close, but still no cigar. If you use Cube() in an expression that has operators with higher precedence than multiplication, the (a)*(a)*(a) will be torn apart. To prevent that, enclose the whole expression in parentheses:

#define Cube( a ) ((a)*(a)*(a))

Surround multiple-statement macros with curly braces. A macro can have multiple statements, which is a problem if you treat it as if it were a single statement. Here's an example of a macro that's headed for trouble:

C++ Example of a Nonworking Macro with Multiple Statements

Example 7-13. 

#define LookupEntry( key, index ) 
   index = (key - 10) / 5; 
   index = min( index, MAX_INDEX ); 
   index = max( index, MIN_INDEX );
...

for ( entryCount = 0; entryCount < numEntries; entryCount++ )
   LookupEntry( entryCount, tableIndex[ entryCount ] );

This macro is headed for trouble because it doesn't work as a regular function would. As it's shown, the only part of the macro that's executed in the for loop is the first line of the macro:

index = (key - 10) / 5;

To avoid this problem, surround the macro with curly braces:

#define LookupEntry( key, index ) { 
   index = (key - 10) / 5; 
   index = min( index, MAX_INDEX ); 
   index = max( index, MIN_INDEX ); 
}

The practice of using macros as substitutes for function calls is generally considered risky and hard to understand—bad programming practice—so use this technique only if your specific circumstances require it.

Name macros that expand to code like routines so that they can be replaced by routines if necessary. The convention in C++ for naming macros is to use all capital letters. If the macro can be replaced by a routine, however, name it using the naming convention for routines instead. That way you can replace macros with routines and vice versa without changing anything but the routine involved.

Following this recommendation entails some risk. If you commonly use ++ and – as side effects (as part of other statements), you'll get burned when you use macros that you think are routines. Considering the other problems with side effects, this is yet another reason to avoid using side effects.

Limitations on the Use of Macro Routines

Modern languages like C++ provide numerous alternatives to the use of macros:

• const for declaring constant values

• inline for defining functions that will be compiled as inline code

• template for defining standard operations like min, max, and so on in a type-safe way

• enum for defining enumerated types

• typedef for defining simple type substitutions

As Bjarne Stroustrup, designer of C++ points out, "Almost every macro demonstrates a flaw in the programming language, in the program, or in the programmer…. When you use macros, you should expect inferior service from tools such as debuggers, cross-reference tools, and profilers" (Stroustrup 1997). Macros are useful for supporting conditional compilation—see Debugging Aids—but careful programmers generally use a macro as an alternative to a routine only as a last resort.