Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-205

Disallow "if False:" for "block comments" in python



    • Type: RFC
    • Status: Implemented
    • Resolution: Done
    • Component/s: DM
    • Labels:


      There seems to be an unwritten convention in LSST to use if False: to "comment out" blocks of python code. I had a community post about why this is bad practice in December 2015, but didn't get much discussion at the time. Since it's come up again in some reviews, I'd like to address it head on here. (note: The same arguments apply to if True:.)

      The argument I've been given about this is that it's a "pythonification of a C++ standard," referencing this C++ standards page. Using #if 0 (or equivalent) in C++ makes some sense in light of the C pre-processor. In python, if debugFlag is True: is useful for code one wants to turn on/off with a high level flag. However, if False: it is a very poor choice for python for the following reasons:

      1. the code is still run by the interpreter.
      2. it doesn't look like a comment: editors show it as valid code.
      3. when reading the code, you have to visually parse the if block to realize it is unused.
      4. the code is now at a different indentation level, potentially causing problems if the code is restored, and potentially messing up auto-indent of subsequent else: blocks, if there are if statements inside the if False.
      5. It's no easier than commenting with #: editors can trivially prepend {{# }} to a region of code with a single keystroke.
      6. it's not pythonic: it is rarely used by python developers who were not first C/C++ developers, and it is not a generally accepted community "block comment" method (pre-pending # or triple-quotes are the standard).

      Our python coding standards say nothing about disallowing commented-out code blocks in production code. I generally agree that that is good practice-I would suggest we discourage but not disallow it-but using if False is much worse than commenting out the code blocks with #, for the above reasons.

      Our python coding standards say nothing about any of this. I believe our standards should explicitly disallow if True:/if False: in all cases, and discourage commented-out code, with exceptions allowed for if the code includes a comment with a clear timeline for when that block would be either removed or integrated back (e.g. Jira ticket number).


          Issue Links


            Parejkoj John Parejko created issue -
            Parejkoj John Parejko made changes -
            Field Original Value New Value
            Link This issue relates to DM-7532 [ DM-7532 ]
            Parejkoj John Parejko made changes -
            Resolution Done [ 10000 ]
            Status Proposed [ 10805 ] Adopted [ 10806 ]
            Parejkoj John Parejko made changes -
            Status Adopted [ 10806 ] Implemented [ 11105 ]


              Parejkoj John Parejko
              Parejkoj John Parejko
              Colin Slater, David Reiss, John Parejko, John Swinbank, Jonathan Sick, Kian-Tat Lim, Mario Juric, Michael Wood-Vasey, Nate Pease [X] (Inactive), Paul Price, Robert Lupton, Russell Owen, Simon Krughoff, Tim Jenness
              0 Vote for this issue
              14 Start watching this issue


                Planned End:


                  No builds found.