classification
Title: Reconciling IDLE's Comment Out Region / Uncomment Region with PEP 8 guidelines for commenting
Type: behavior Stage: resolved
Components: Documentation, IDLE Versions: Python 3.8
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: anthropologist, docs@python, gvanrossum, terry.reedy
Priority: normal Keywords:

Created on 2020-07-01 15:24 by anthropologist, last changed 2020-07-01 17:43 by gvanrossum. This issue is now closed.

Messages (3)
msg372757 - (view) Author: Anthropologist (anthropologist) Date: 2020-07-01 15:24
IDLE's Comment Out Region formatting tool currently adds two octothorpe characters followed by no spaces.  The Uncomment Region tool removes up to 2 octothorpes but does not remove spaces. 

The Python Style Guide (PEP 8) specifies that: "An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space."

I propose reconciling these conflicting approaches to commenting out code, either by changing IDLE's behavior (i.e., instead of ##, Comment Out Region should insert # followed by a space, per PEP 8), or by amending the Python Style Guide to provide clear instructions about commenting out code, which is arguably a different use of comments than a single-line comment for the sake of explaining code. 

If the resolution involves changing IDLE's behavior, the Uncomment Region feature should also be changed to remove the space character after the octothorpe. As it currently stands, this feature fails to uncomment code that has been manually commented out following the guidelines in PEP 8.
msg372772 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-07-01 17:26
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.
msg372774 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2020-07-01 17:43
The IDLE feature should not change, for all the reasons Terry have.

I am quite done with changes to PEP in order to settle arguments, and I do not believe this convention needs mentioning in that PEP. Remember there is text in PEP 8 reminding readers to use your best judgment.
History
Date User Action Args
2020-07-01 17:43:00gvanrossumsetstatus: open -> closed
resolution: not a bug
messages: + msg372774

stage: resolved
2020-07-01 17:26:41terry.reedysetnosy: + gvanrossum
messages: + msg372772
2020-07-01 15:24:15anthropologistcreate