Dr. Dobb's | More on the C/C++ Comment Macro for Debug Statements

More on the C/C++ Comment Macro for Debug Statements

A portable technique for managing multi-line debug statements.

February 01, 2003
URL:http://www.drdobbs.com/more-on-the-cc-comment-macro-for-debug-s/184401612

More on the C/C++ Comment Macro for Debug Statements A C/C++ Comment Macro" by Mark Timperley in the January 2001 issue of C/C++ Users Journal suggested a macro definition to comment out a single-line debug statement. The tip created a macro to represent two slash characters (//) as the beginning of a single-line statement. For debug builds, the single line compiled. For release builds, the line was interpreted as a comment. Mr. Timperley elaborated a token-pasting operator in a second macro, SLASH(), in order to compose the two slash characters as shown:

 #define COMMENT SLASH(/)
 #define SLASH(s) /##s
 
 #if _DEBUG
 #include <iostream>
 #define dout std::cout
 #else
 #define dout COMMENT
 #endif
 
 dout << "Hello World!\n";

However, this approach is limited to only single-line debug comments, and its utility relies on the compiler implementation (i.e., the implementation of the C/C++ preprocessor). For instance, some preprocessor implementations do not immediately interpret the macro token-pasting operation used in another macro definition. These preprocessors will define the macro COMMENT as a "SLASH(/)" char string instead of "//" as desired. Hence, this approach may not be portable across different compilation environments. This technique also does not satisfy the scenario where the debug statements are formatted into multiple lines to improve legibility. For example, in the following code segment:

 dout << "variable a: " << a // a is an integer
 << "variable b: " << b /* b is a double */
 << "variable c: " << c // c is a char
 << endl;

Only the first line will be commented out, and the rest of the lines will cause compilation errors. (Note that I included the comment control characters /*, */, and // in the preceding code segment to increase the complexity.)

A recent assignment at FedEx Services ITD achieved a couple of portable C/C++ comment macro definitions that are able to handle multiple-line debug statements in both function (dbgInC) and class (dbgInCpp) formats. An example of these useful and portable macro tricks is illustrated below:

 #if _DEBUG
 // dbgInC defined as "printf" or other custom debug function
 #define dbgInC printf
 // dbgInCpp defined as "cout" or other custom debug class
 #define dbgInCpp cout
 #else
 // dbgInC defined as null [1]
 #define dbgInC
 // dbgInCpp defined as "if(0) cerr" or "if(1); else cerr"
 #define dbgInCpp if(0) cerr
 #endif
 
 dbgInC("Debug in C: %d%s%2.0f\n",
 a, // a is an integer
 b, /* b is char array */
 c); // c is a float
 
 dbgInCpp << "Debug in C++: "
 << a // a is an integer
 << b /* b is char array */
 << c // c is a float
 << endl;

When compiled, dbgInC is interpreted as null by the preprocessor, and dbgInCpp is interpreted as a "if(0) cerr" string.

The function dbgInC is converted to an expression that does not cause a compilation error but returns a true/false value at run time.

 ("Debug in C: %d%s%2.0f\n", a, b, c);

And dbgInCpp is converted to an if-condition whose statement, cerr << ..etc., will never be reached at run time.

 if(0)
 cerr << "Debug in C++: " << a << b
 << c << endl;
 
 or [2]:
 
 if(1);
 else
 cerr << "Debug in C++: " << a << b
 << c << endl;

The proposed comment macro definitions convert the debug statements into unrelated C/C++ code and are not limited by the implementation of the C/C++ preprocessor. Thus, they are highly portable across different compilers. But, will code conversion by macro definition affect the run-time performance significantly? I conducted a performance test of the above conversion macro approach against blank-test sample code where the debug statements were actually removed. Interestingly, the performance measurement showed the proposed conversion macro suffered merely a nonessential loss (less than 1~2%) versus the ideal blank test with Forte 6.2, the Sun Workstation Pro C++ compiler.

Notes

[1] Or, similar to dbgInCpp:

 #define dbgInC if(0) printf

[2] With appropriate compiler optimization level (e.g. -xO4 in Forte 6.2, Sun Workstation Pro C++ compiler), the if(0) condition and its statements can be stripped from the assembly code of compilation by the C++ preprocessor. Thus, the debug segment is actually removed from the code at release builds.

About the Author

Randall C. Chang graduated with a Ph.D. in electrical and computer engineering from University of Florida. Since 1994, he has provided computer software consulting services in the central Florida area to corporations such as Florida Power Corporation, Lucent Technologies, Inc., etc. He currently works as a technical advisor for FedEx Services Information Technology Division and teaches C++/Java programming language courses in the Management Information Systems Department at University of Central Florida.