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

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

    XMLWordPrintable

    Details

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

      Description

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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              Parejkoj John Parejko
              Reporter:
              Parejkoj John Parejko
              Watchers:
              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
              Votes:
              0 Vote for this issue
              Watchers:
              14 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:
                Planned End:

                  Jenkins

                  No builds found.