This is an archive of the discontinued LLVM Phabricator instance.

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

Authored by andreybokhanko on Aug 11 2016, 5:44 AM.

Details

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

Diff Detail

Event Timeline

andreybokhanko retitled this revision from to Remove suggestion to use if 0 ... undef for large blocks of comments.
andreybokhanko updated this object.
andreybokhanko added a subscriber: llvm-commits.
andreybokhanko retitled this revision from Remove suggestion to use if 0 ... undef for large blocks of comments to Remove suggestion to use "#if 0" ... "#endif" for large blocks of comments.Aug 11 2016, 6:17 AM
lattner edited edge metadata.Aug 11 2016, 9:36 AM

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 :-)

lattner accepted this revision.Aug 11 2016, 9:36 AM
lattner edited edge metadata.
This revision is now accepted and ready to land.Aug 11 2016, 9:36 AM
andreybokhanko added a comment.EditedAug 12 2016, 3:20 AM

@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

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

chandlerc edited edge metadata.Aug 16 2016, 7:46 PM

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

andreybokhanko retitled this revision from Remove suggestion to use "#if 0" ... "#endif" for large blocks of comments to Clarify suggestion to use "#if 0" ... "#endif" for large blocks of comments.
andreybokhanko updated this object.
andreybokhanko edited edge metadata.

Chris, Chandler, thank you for the review!

Patch updated.

This revision was automatically updated to reflect the committed changes.