Author terry.reedy
Recipients anthropologist, docs@python, gvanrossum, terry.reedy
Date 2020-07-01.17:26:40
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1593624401.75.0.716854407155.issue41184@roundup.psfhosted.org>
In-reply-to
Content
Guido, do you think PEP 8 should say anything about Comment-out Blocks?  It would not hurt, but one could say that since they are part of code development, and not usually a permanent part of committed code, they are out of scope, like choice of editor.  On the other hand, if they are left in stdlib code, I think that they should at least be distinct from text comments.  I presume that whoever added this feature to IDLE followed pre-existing practice.

Anthropolist: The comment-out feature predates my involvement with IDLE, but it is a useful feature for code maintenance.  Comment-out blocks are not inline comments.  They are more like comment blocks, which PEP 8 discusses just above inline comments.  However, the context natural language, default English, comments, so the guidelines do not apply.  Disabled code blocks have a different purpose and lifetime and in my opinion should be visually distinct.

If one manually comments out code with single hashes on the left margin, like so:
#def f():
#    def b():
#        nonlocal c
Uncomment Region will remove them.

If comment-out hashes are indented, like so
    ##def f():
    ##    def b():
    ##        nonlocal c
one can dedent and then uncomment.  Indeed, one can dedent, comment-out, and indent to add such to code.
---

I recursively grepped 3.9 /Lib for lines containing '##' and got 1596. Some are header or separator lines.  Some are emphasized text comment blocks (sometimes with '###').  Some xml and xmlrpc files have a convention of prefixing comment blocks with a line containing only '##'.

There are at least a few hundred commented-out code lines, perhaps half in idlelib, and mostly in tests.  Sometimes '##' is followed by a space, even within idlelib.  Sometimes '##' is indented instead of flush left.  

I suspect that these differences are editor related.  An editor aimed at experts, which is not IDLE, might have comment-out and uncomment options to adjust the number of #s, a following space or not, and an indent or not.
History
Date User Action Args
2020-07-01 17:26:41terry.reedysetrecipients: + terry.reedy, gvanrossum, docs@python, anthropologist
2020-07-01 17:26:41terry.reedysetmessageid: <1593624401.75.0.716854407155.issue41184@roundup.psfhosted.org>
2020-07-01 17:26:41terry.reedylinkissue41184 messages
2020-07-01 17:26:40terry.reedycreate