[PATCH] D23404: Remove suggestion to use "#if 0" ... "#endif" for large blocks of comments

[Andrey Bokhanko via llvm-commits]

andreybokhanko added a comment.

@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 changes 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


https://reviews.llvm.org/D23404