The Psychology of Quality and More

C Style: Standards and Guidelines (contents)

CHAPTER 4 : Commenting

PART 2 : COMMENTING AND NAMING

CHAPTER 4 : Commenting
4.1 Commenting fundamentals
4.2 Comment types
4.3 Header comments
4.4 File Header comment
4.5 Function header comments
4.6 Block comments
4.7 Trailing comments
4.8 Commenting data
4.9 The preprocessor and comments
4.10 Summary 

<--Prev page | Next page -->

4.9 The preprocessor and comments

Comments are typically removed by the preprocessor. Thus, they can be put virtually anywhere, except inside quoted strings (although some compilers have trouble with this!).

4.9.1 Nesting comments

Comments do not nest, although some compilers still allow it. It is simply bad practice to ever do this (even if you did, it could be difficult to find matching start and end tokens). Complete areas of code can still be 'commented out' (a practice which can be useful during debugging) by using conditional compilation. '#if 0...#endif' works, but is a little unclear. '#ifdef UNDEFINED...#endif' is better. The non-compiled code can be isolated further from the rest of the code by using comment bars to delimit the commented-out section:

#ifdef UNDEFINED /** COMMENTED OUT CODE

#ifdef UNDEFINED /** COMMENTED OUT CODE *************************************/
...
commented out code
...
#endif /** END OF COMMENTED OUT CODE ****************************************/

--------------------------------------------

<--Prev page | Next page -->