Clarify suggestion to use "#if 0" ... "#endif" for large blocks of comments

[andreybokhanko]

Summary

CodingStandards say:

"To comment out a large block of code, use `#if 0 and #endif`. These nest properly and are better behaved in general than C style comments."

I can't find a single instance of using this approach in llvm+clang sources. All the cases of #if 0 usage are to disable real code. Thus, I believe this suggestion is misguiding and propose to clarify it.

Andrey

[lattner]

I'm +1 for this change. While this is a good suggestion for local development of code when you're working on it, we don't want large blocks of code to be checked into the source tree. This document doesn't need legislate how you do your local development :-)

[andreybokhanko]

@lattner, thank you for the quick review -- I hoped / feared for more discussion! :-)

To clarify, my reading of this paragraph (written in "Comment Formatting" section of the guide!) is that one should use #if 0 ... #endif to create large blocks of comments. After some digging, I found a single case of such usage, in include/llvm/Support/GenericDomTreeConstruction.h:

  // This is more understandable as a recursive algorithm, but we can't use the
  // recursive algorithm due to stack depth issues.  Keep it here for
  // documentation purposes.
#if 0
... // some code left for documentation
#else
... // some real code
#endif

All other usages are to disable code from being compiled (usually some code for debug output), like this (from include/llvm/ADT/SCCIterator.h):

#if 0 // Enable if needed when debugging.
  dbgs() << "TarjanSCC: Node " << N <<
        " : visitNum = " << visitNum << "\n";
#endif

My proposal is not to ban latter usages, but to remove / change the paragraph in "Comment Formatting" section -- to make it clearer for people like me. :-)

It can be changed as follows:

Commenting out large blocks of code is discouraged, but if you really have to do this (for documentation purposes or as a suggestion for debug printing), use ``#if 0`` and ``#endif``. These nest properly and are better behaved in general than C style comments.

Please let me know what your preference is.

Andrey

[lattner]

I think this approach (adding "Commenting out large blocks of code is discouraged, ...") is great!

[chandlerc]

(FWIW, +1 from me to the suggested more explicit wording.)

[andreybokhanko]

Chris, Chandler, thank you for the review!

Patch updated.

llvm/trunk/docs/CodingStandards.rst

 #. When writing C code: Obviously if you are writing C code, use C style
    comments.
 
 #. When writing a header file that may be ``#include``\d by a C source file.
 
 #. When writing a source file that is used by a tool that only accepts C style
    comments.
 
-To comment out a large block of code, use ``#if 0`` and ``#endif``. These nest
-properly and are better behaved in general than C style comments.
+Commenting out large blocks of code is discouraged, but if you really have to do
+this (for documentation purposes or as a suggestion for debug printing), use
+``#if 0`` and ``#endif``. These nest properly and are better behaved in general
+than C style comments.
 
 Doxygen Use in Documentation Comments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Use the ``\file`` command to turn the standard file header into a file-level
 comment.
 
 Include descriptive paragraphs for all public interfaces (public classes,