How to Add Comments to Macros

Comments are an important part of documenting your code.

Adding comments to macros is quite easy, but it has to be done the right way.

This works with both C and C++ compilers.

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

4 Comments

  • brian says:

    Now I feel stupid. That’s cleared it up for me

    • admin says:

      There is nothing wrong with getting that “Aha!” moment. You’ve learned something.
      Thanks for the comment.

  • Caterina says:

    Serious follower with this page, a bunch of your blog posts have seriously helped me out. Awaiting more posts!

    • admin says:

      Thank you for the praise! More posts will be coming.
      If there are topics or subjects you would like to see articles on, then let me know and I will see what I can do.