PyCQA / docformatter

Formats docstrings to follow PEP 257
https://pypi.python.org/pypi/docformatter
MIT License
524 stars 61 forks source link

Add option to avoid breaking a single word into a new line #241

Open ThiefMaster opened 1 year ago

ThiefMaster commented 1 year ago

I don't know in which formatter I saw this (might have been ruff but can't find it there anymore), but one of them has this really nice feature that minor max-line-length violations are acceptable, if wrapping would result in ugliness. In particular this means that it will not auto-wrap a comment if the next line would contain just one word. It would either wrap earlier (to have 2-3 words in the new line) or accept that the line will be slightly longer than the usual maximum.

electric-coder commented 11 months ago

I don't know in which formatter I saw this

It was likely the 10% line-length rule from Black:

Line length

(...) Black defaults to 88 characters per line, which happens to be 10% over 80.

(...) Black will try to respect that. However, sometimes it won’t be able to without breaking other rules. In those rare cases, auto-formatted code will exceed your allotted limit.

The problem is if you're setting --line-length = 88 Black will still give you a few characters extra, but Flake8 will never be happy with the result and will trigger warnings. Black recommends using flake8-bugbear but flake8 is an order of magnitude more popular.

It would either wrap earlier (to have 2-3 words in the new line)

There should be a style guide quoted backing up this option.