[issue41184] Reconciling IDLE's Comment Out Region / Uncomment Region with PEP 8 guidelines for commenting
New submission from Anthropologist <python@anthropo.org>: 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. ---------- assignee: docs@python components: Documentation, IDLE messages: 372757 nosy: anthropologist, docs@python, terry.reedy priority: normal severity: normal status: open title: Reconciling IDLE's Comment Out Region / Uncomment Region with PEP 8 guidelines for commenting type: behavior versions: Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41184> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- nosy: +gvanrossum _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41184> _______________________________________
Guido van Rossum <guido@python.org> added the comment: 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. ---------- resolution: -> not a bug stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue41184> _______________________________________
participants (3)
-
Anthropologist -
Guido van Rossum
-
Terry J. Reedy