Formatter: wrap comments (E501)

[kdeldycke]

Playing with the beta formatter, I was curious why it did not wrap long comments.

See the following long.py file:

def test():
    # This is a very very very very very very very very very very very very very very very very very long comment.
    pass

Running the latest ruff version, the file is left unchanged, while I expected the long comment line to be wrapped:

$ ruff --version
ruff 0.0.289

$ ruff format ./long.py
warning: `ruff format` is a work-in-progress, subject to change at any time, and intended only for experimentation.
1 file left unchanged

I then realized that Black itself doesn't format comments. Even in its last iteration:

$ black --version
black, 23.9.1 (compiled: yes)
Python (CPython) 3.11.5

$ black --preview ./long.py
All done! ✨ 🍰 ✨
1 file left unchanged.

Wrapping comments would be a nice quality of life improvement to auto-fix a number of E501 rule violations.

[kdeldycke]

Possibly related issues:

• Auto-fix line length (E501) #7361
• Measuring LineSuffix when formatting to include trailing comments #5630
• Ignore pragma when considering E501 #3894
• Implement autoformat capabilities #1904 (comment)
• Possibility to implement flake8-length into ruff #4595
• D200 conflicts with E501/W505. #6269
• Disable E501 for inline comments #7400
• Implement autoformat capabilities #1904
• Implement remaining pycodestyle rules #2402

[zanieb]

Hey @kdeldycke — I think there are some fair concerns raised in the Black issue but thanks for starting the discussion!

Out of curiosity, would docstring formatting resolve most of your needs here?

[kdeldycke]

In the mean time, autopep8 is supporting comment wrapping. You can perform this task and this only with the following one-liner:

$ autopep8 --in-place --max-line-length 88 --select E501 --aggressive ./long.py

$ cat ./long.py

def test():
    # This is a very very very very very very very very very very very very
    # very very very very very long comment.
    pass

$ autopep8 --version
autopep8 2.0.4 (pycodestyle: 2.11.0)

[kdeldycke]

Hey @kdeldycke — I think there are some fair concerns raised in the Black issue but thanks for starting the discussion!

Oh yes. I'm just starting to understand the complexity of the issue. It's hard to generalize comment autoformat. Especially because of the line-dependency of # pragma kind of comments. I haven't looked into ruff code so I have no idea how hard and how feasible is it to handle these two situations.

Out of curiosity, would docstring formatting resolve most of your needs here?

Oh you mean moving this long comment into a docstring? On paper yes. And yes, I guess when comments become that long, it is time to consider moving them into your function's docstring.

I still have the case in which I need long comments: to not have them appears in the auto-generated Sphinx documentation. I have some places in my code where I need long explanation of implementation details, but don't want to distract the user of my library with these implementation details in the top-level documentation.

[ngnpope]

I've just come across this again and wanted to throw in something for consideration if this gets implemented...

Some directives in Sphinx, e.g. autodata, have a special comment notation to indicate that the comment should be used for documentation, e.g.

#: A generic type variable.
T = TypeVar("T")

It would be nice to preserve the correct comment marker when wrapping, i.e. the following:

#: This is a very very very very very very very very very very very very very very very very very long comment.
MAGIC_NUMBER = 123

...after formatting would produce:

#: This is a very very very very very very very very very very very very very very very
#: very very long comment.
MAGIC_NUMBER = 123

...and not this:

#: This is a very very very very very very very very very very very very very very very
# very very long comment.
MAGIC_NUMBER = 123

Another thing for consideration might be what happens with comment tags, as defined in lint.task-tags. How should these wrap?

Like this?

# TODO: This is a very very very very very very very very very very very very very very
# very very very long comment.

Or like this? (Which I personally like...)

# TODO: This is a very very very very very very very very very very very very very very
#       very very very long comment.