black: Line too long: Comments

I’m going to go ahead and say that Black will not split comments.

• Many comments are used by various tools with special meaning (# type, # noqa, etc.), and splitting them up will break them. We can hardcode support for some pattern, but it’s going to be a never-ending battle.
• As called out above, splitting up comments can break commented-out code.

This seems risky. Comments are often commented out code or other structured data. I think we should not merge short comments, but splitting long ones is probably OK.

What’s the status of this issue?

In my project, we run black to reformat our files. Then we run pylint, which complains about the long comment lines, and we have to manually (!!) shorten them one-by-one. It always feels strange that I have to do manually something that can be so easily automated, especially considering that we do use a tool (black) whose job is exactly that, to automatically reformat my files.

I understand that there may be complications that I don’t see, and it’s fine to have it as a non-default option. I’ll be happy to see it happen.

Maybe we just need to write a separate tool for this, outside of Black? While I personally would like to have this feature in Black, because it would be convenient for me, I acknowledge that it might not fit with Black’s goals.

i agree, black behaves very oddly with comments

while small_cond:  # long comment here...
    do()

becomes

while (
    small_cond: 
):  # long comment here...
    do()

which neither improves readability, nor keeps the comment on the same line as either the while loop or the condition, which it may have referred to

with regards to comments, i would recommend:

• moving comments to the previous line before splitting
• breaking up comments if they are too long for one line
• avoiding any splitting on lines with linter rules (pylint, noqa)

IE do this

# long comment here...
while small_cond:
    do()

Or this:

while small_cond:  # pylint: long comment breaks line length rules... fix it by hand
    do()

Most likely a new configuration option is a no-go. But seems like there is some acceptance for just splitting them, despite the edge cases. As I said, for starters we could do it for dedicated comment lines only, not inline comments. One discussion that should be had is the style of split. I quite like equalising the line lengths if one would be radically shorter. But that probably is also related to string processing, which I’m not familiar with (yet).

# this is a very long comment that should probably be on multiple lines if I was to decide

# this is a very long comment that should probably be on multiple lines if
# I was to decide

# this is a very long comment that should
# probably be on multiple lines if I was to decide

So I’d prefer the last option.

I would also really love to have this made possible, maybe as a default off option (although Black doesn’t like having too many options, which I respect). For what it’s worth, ClangFormat does reflow comments so they fit within the specified line length, and having used it for a few years now, it rarely causes any annoyance.

My opinion:

I want this feature so much, but I don’t think it is possible to do it in a sensible way.

Does this

# This is me very long comment that is too long for one line.

format to this?

# This is me very long comment that is too long for one 
# line.

Yes.

But what if I remove the very from the last comment

# This is me long comment that is too long for one 
# line.

so that it fits now into one line? Does the comment stay as it is, even if it fits onto one line? Or does it change to

# This is me long comment that is too long for one line.

It stays as it is, and you can manually rewrite it if you want it back on one line.

ClangFormat does it this way, and in my experience it works well.

For comment lines specifically, there is a good chance we’ll never split them. There are other issues in https://github.com/psf/black/labels/F%3A linetoolong that we should fix though.

I’d like to state, that if we take care of some of the simple scenarios here, that it becomes next years default and it’s only gated by the --preview flag. I’m still a big proponent of as little formatting configuration options as possible please.

The concern raised about commented code goes the other way too. If we have a line that is just under the limit, and is then commented, bringing it over the limit, making a new line could break it. Maybe it won’t, but for example this will:

That’s a valid concern, and different from other languages (which would just parse the still valid code and reformat it properly if it gets wonky when un-commenting some code).

I still think this is fine, though. When you uncomment some commented out code, it’s not unreasonable to expect that you also fix it if its formatting gets weird.

[…]

# this is a very long comment that should probably be on multiple lines if I was to decide

# this is a very long comment that should probably be on multiple lines if
# I was to decide

# this is a very long comment that should
# probably be on multiple lines if I was to decide

So I’d prefer the last option.

Just to make this more difficult: I prefer the first. That will generally make diffs smaller, if say I decide to append some more text.

I would go for a config option, something like split-singleline-comments, because as already mentioned in the thread there are complications when it comes to splitting in-line comments and I would like if a default option covered both the cases to avoid confusion.

Also if no-one is currently working on this, can you assign this issue to me, so I can work and open a PR.