[Github-comments] [geany/geany] Python comment as in PEP8 (#1681)

[cousteau]

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
```python
#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
```python
# 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
```python
# return 0
```
that looks to me as a descriptive comment rather than commented-out code, whereas any of
```python
#return 0
#~ return 0
```
look like commented-out lines of code.
And
```python
# ~ 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 or view it on GitHub:
https://github.com/geany/geany/issues/1681#issuecomment-922802580
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.geany.org/pipermail/github-comments/attachments/20210920/0e79dbb8/attachment.htm>