pycodestyle icon indicating copy to clipboard operation
pycodestyle copied to clipboard

More fine-grained control of docstring and comment length

Open McSinyx opened this issue 6 years ago • 2 comments

As discussed/hijacked in #344, I proposed to have an option to limit the length of docstring and comments:

  1. Multi-line docstring: max_doc_length, default to max_line_length (current behavior)
  2. Single-line docstring: max_single_doc_length, default to max_doc_length + 3 if max_doc_length is set, otherwise to max_line_length
  3. Comment block: max_comment_length, default to max_doc_length (current behavior)

Answer to @asottile

I don't think the complexity of a bunch of new settings is a good idea -- also your current proposal allows single line docstrings to extend beyond max_line_length

I added that to the proposal. My rational is, consider these

"""Something that span 72 columns.

Some additional description.
"""

"""The same first line."""

then the second case actually reaches 75 columns. I'm not sure about others, but I consider

"""Blah blah blah.
"""

to be quite distasteful.

Answer to @timj

I'm really happy with the current situation and have no problem forcing my comment lines to match the docstring constraint.

Generally, I have no problem with breaking comments, but in a few places like copyright headers, it's not very nice, like in AGPL or LGPL:

# foobar is free software: you can redistribute it and/or modify it
# under the terms of the GNU Lesser General Public License as published
# by the Free Software Foundation, either version 3 of the License,
# or (at your option) any later version.
#
# foobar is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with foobar.  If not, see <https://www.gnu.org/licenses/>.

As you can see, the second-last line is 74 columns, and breaking it in any manner makes it look awkward, especially when these should be consistent between different languages.

Also to @brianv0, what's your opinion on this?

McSinyx avatar Feb 05 '20 07:02 McSinyx