How to Add Comments to Macros

The easiest way to document macros is to just add comments before or after the macro definition:

// returns the larger of the two arguments
#define MAX(x, y) (x)>(y)?(x):(y)

This works well for small macros, but if you have a larger macro that is spread over several lines, it might be nice to put comments nearer some tricky or crucial bit of code. You can do that by using C-style comments (/**/). The preprocessor treats comments as white space, so comments of the form /* some sort of comment */ are treated as white space.

#define TRANS_TEST(a, b, c) \
{   /* variables to store intermediate results*/ \
    bool aGb = false;\
    bool bGc = false;\
    if (a > b) \
    {\
        aGb = true;
        printf("'a' is larger than 'b'\n");\
    }\
    if (b > c) \
    {\
        bGc = true;
        printf("'b' is larger than 'c'\n");\
    }\
    /* do the transitivity test */ \
    if (aGb &&  bGc) \
    {\
        printf("by transitivity we know 'a' is larger than 'c'\n");\
    }\
}

The above (contrived) example, determines if parameter a is greater than parameter c by using the principle of transitivity.

C style comments were used to document the code. Note the line splicing (\) operator appears at the end of each line.

When this code is compiled, the preprocessor will treat the comment (and any white space surrounding it) as white space.

NOTE: Using C++ single line comments (//)won’t work because everything following the // until the end of the line is considered white space. Even if the macro is spread over several lines using the line splicing (\) operator, the preprocessor turns it into a single line and everything following the // will be considered part of the comment (hence, white space).

#define TRANS_TEST(a, b, c) \
{   // variables to store intermediate results \
    bool aGb = false;\
    bool bGc = false;\
    if (a > b) \
    {\
        aGb = true;
        printf("'a' is larger than 'b'\n");\
    }\
    if (b > c) \
    {\
       bGc = true;
       printf("'b' is larger than 'c'\n");\
    }\
    // do the transitivity test  \
    if (aGb &&  bGc) \
    {\
        printf("by transitivity we know 'a' is larger than 'c'\n");\
    }\
}

In the above example, the C++ single line comment was used. When it is processed by the preprocessor, everything until the end of the line (after all the lines have been spliced together) will be considered a comment. Consequently, the compiler will issue an error because all it will see is:

#define TRANS_TEST(a, b, c) {