Dr. Dobb's | C/C++ Tip #5: A C/C++ Comment Macro

C/C++ Tip #5: A C/C++ Comment Macro

For a non-intrusive debugging macro, this one-liner is hard to beat.

January 01, 2001
URL:http://www.drdobbs.com/cc-tip-5-a-cc-comment-macro/184401344

January 2001/C/C++ Tip: A C/C++ Comment Macro

A potentially useful macro is one that would expand to become a single-line comment. Creating such a macro, however, is less than straightforward. As you may recall, the C/C++ preprocessor interprets two slash characters (//) as the beginning of a single-line comment. Attempting to directly define the two slash characters causes the preprocessor to interpret the text as a definition followed by a comment (as in the following example):

#define COMMENT // this obviously doesn't work!

Since the two slash characters cannot be defined directly, another approach is required. By using the token-pasting operator (##), the "//" can be constructed from two single '/' characters. While this may sound like I’m repeating myself, it works because a single slash character that is not followed directly by a single slash character is ignored by the preprocessor. Therefore it is possible to define a COMMENT macro in terms of a second macro, which I’ve named SLASH, by combining the token-pasting operator and a macro with a '/' parameter:

#define COMMENT SLASH(/)
#define SLASH(s) /##s

The COMMENT macro is useful in creating flexible debug diagnostics that can be removed by the preprocessor. As an example, I will define a macro named DEBUG_ONLY. Preceding any line of code with the DEBUG_ONLY macro will cause that line of code to be compiled only for debug builds. For release builds, the DEBUG_ONLY macro will be interpreted by the preprocessor as a single-line comment. The greatest advantage of this approach is that any valid single-line expression can be used to convey debug information, which makes this method more flexible than other parameterized macro approaches. Also, this method is completely portable. The macros are defined as follows. (Assume that in a debug build _DEBUG is defined for both the preprocessor and the compiler, or substitute the symbol used by your compiler.)

#if _DEBUG
#define DEBUG_ONLY
#else
#define DEBUG_ONLY COMMENT
#endif

The macro can be used like this (in C++):

DEBUG_ONLY if (x>100) std::cout << "WARNING! x=" << x <<"\n";
DEBUG_ONLY std::cout << "Hello World!\n";

As a further refinement to this example, I’ve replaced DEBUG_ONLY cout with the macro dout, which is short for debug output. The macro is defined and used as follows:

#if _DEBUG
#include <iostream>
#define dout std::cout
#else
#define dout COMMENT
#endif

dout << "Hello World!\n"; // Now doesn't that look sharp!

The COMMENT macro not only lends greater flexibility to creating debug output, but it can make code that includes it look much cleaner. These macros have been tested successfully with a variety of preprocessors. The only known caveat is that some older C preprocessors do not recognize the "//" character sequence as a single-line comment, so these macros will not work for these preprocessors.

A header file containing this and other useful macros is available on the CUJ website (www.cuj.com/code/).

I just read your C/C++ Tip #5, published in the January 2001 issue of CUJ. The content of the tip (doing a macro that expands into a comment) was quite familiar, since I'd seen a similar method deployed in one of Microsoft's header files. However, the tip is very incorrect.

The writer uses token pasting to construct a comment start sequence. However, this is invalid according to the C and C++ Standards. In section 5.1.1.2 of ISO C (1999), titled "Translation phases," comment processing occurs in phase 3 where the preprocessor identifies tokens and whitespace, with comments replaced with whitespace. Macro processing is then done in phase 4, and that phase is the one in which these new comment start sequences would be introduced. There is no followup phase after #4 where the comment would be recognized, so eventually a conforming compiler would reject the program text due to an illegal token — '//'. The 1998 C++ Standard has similar language in section 2.1, "Phases of translation [lex.phases]."

Some compilers mix the order and processing of phases sufficiently to allow this macro to work, Microsoft's Visual C++ 6.0 being notable for its popularity. Others, such as the Metrowerks CodeWarrior C/C++ compilers (upon which I worked for over two years as a compiler engineer before my current employment) follow the Standard and will reject the usage shown in the tip.

Thanks,

Ben Combee
Lead Software Architect
Veriprise Wireless
<http://www.veriprise.com>

We therefore want to caution readers that this tip is not portable and probably should not be used in production code. — mb.