Sorry to revive an old discussion, but I think this is a misinterpretation of PEP8, and that you may want to consider reverting #1682. PEP8 refers exclusively to descriptive comments, not commented-out code.

PEP8 makes these statements about comments which shows that they aren't referring to commented-out code (and which cannot possibly be applied to commented-out code):

• "Comments should be complete sentences." A commented-out line of code is a Python statement, not an English sentence.
• "The first word should be capitalized, unless it is an identifier that begins with a lower case letter." Commented-out code is always going to start with an identifier (or a keyword), so this requirement would never apply.
• "Comments that contradict the code are worse than no comments. Always make a priority of keeping the comments up-to-date when the code changes." By its nature, commented-out code precisely contradicts the actual code, as it is a line of code that is not interpreted; it has been removed from the program or replaced by something else; so what that line describes is not part of the program.

The main reason I think #1682 should be reverted is also (probably) the reason why PEP8 recommends adding a space after the #: that space improves readability of the comment, but for commented-out code you'd rather want to "obscure" it. I find that removing that space has precisely that "psychological effect".
For example, if I see

#return length

my brain sort of "chokes" on that weird #return "word", and my natural reaction is to ignore the rest as gibberish.
But if I see something readable, like

# Return the length

that "passes the filter" and my natural reaction is to read the rest.

For this reason, I've somehow gotten used to distinguish comments and commented-out code based on whether there is a space or not. So if I see

# return 0

that looks to me as a descriptive comment rather than commented-out code, whereas any of

#return 0
#~ return 0

look like commented-out lines of code.
And

# ~ return 0

looks just weird.

This convention seems to be used extensively in Linux config files such as .bashrc and /etc/default/grub, where descriptive comments always start with #-space, and commented-out lines that users may want to uncomment always start with a single # and no space.
Personally I think this distinction is good practice, and have set it that way in filetypes.python myself, but I think this should be the default behavior.

What do you think?

(PS: One argument against this is if users use the "Comment Line(s)" feature to quickly create block comments after typing the whole paragraph without #'s, but I don't think people do that often... do they?)

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications on the go with GitHub Mobile for iOS or Android.