Section should really be titled: Use of White Space and comments with Conditional Compiler Directives.
Like other language constructs, compiler directives have a set of formatting rules to abide by.
Conditional directives must be the first non-whitespace character on a line.
Spaces may appear between the pound sign (#) symbol and the directive to aid readability.
Use of Comments
When the compiler begins processing a source file containing compiler directives, it looks for lines containing compiler directives and either includes or excludes them, depending on the result of their expression when itÆs evaluated. Because of this, itÆs very important that comments related to the directive be properly formatted to take this into consideration. If these rules are not abided, errors may result once the compiler begins compiling the resulting source code.
Rules
Single line comments may appear on the line after well-formed conditional compiler directives. These are ignored by the compiler. The reason for this behavior is that the compiler will completely discard a line containing a conditional compiler directive.
Example:
#define DEBUG // This comment will be ignored
With this behavior, mult-line comments should not begin or end on a line with conditional compilation directives unless the comment encompasses the directive. Consider:
#if DEBUG /* thisà
* is not a fine thing.
*/ #define DEBUG /** @deprecated */ is useless at best, and misleading at worst. It will not have the effect of deprecating the subsequent member û the compiler will discard the entire line, including the comment.
Documentation comments with pragma tags can be included in conditional blocks, providing the comments are not included on the same line as the conditional directive, like so:
#if DEBUG
/** @deprecated */
#endif A last note on conditional directives and comments. Conditional compiler directives embedded in comments will be ignored û the compiler will not parse into comments looking for directives. Comments essentially take precedence over conditional compilation directives.
Example:
/* this directive is completely ignored
* #undef DEBUG
*/Conditional directives must be the first non-whitespace token on a line. White space may appear between the # symbol and the directive. Whitespace before and after the # symbol allows for flexible indentation by the developer.
Single line comments may appear on the line after well-formed conditional compilation directives. These are ignored by the compiler. Multiline or block comments should not be used on the same line as conditional directives as the directive line is thrown away during compilation leaving a malformed block comment.
Doc comments with pragma tags can be included in conditional blocks, for example to conditionally deprecate members:
#if DEBUG
/** @deprecated */
#endif
Conditional compilation directives in comments are ignored û the compiler will not parse into