[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH v4 02/19] flake8: Enforce shorter line length for comments an

From: John Snow
Subject: Re: [PATCH v4 02/19] flake8: Enforce shorter line length for comments and docstrings
Date: Fri, 9 Apr 2021 13:08:54 -0400
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.8.1

On 4/9/21 5:33 AM, Markus Armbruster wrote:
Daniel P. Berrangé <berrange@redhat.com> writes:

On Fri, Mar 26, 2021 at 04:44:25PM +0000, Peter Maydell wrote:
On Fri, 26 Mar 2021 at 16:33, John Snow <jsnow@redhat.com> wrote:
Being less terse about it: Mostly, I don't like how it enforces this
column width even for indented structures. Generally, we claim that 72
columns is "comfortable to read" and I agree.

                                     However, when we start in a margin, I
                                     am not convinced that this is
                                     actually more readable than the
                                     alternative. We aren't using our full
                                     72 characters here.

I agree, and I don't see any strong reason to hold our Python
code to a different standard to the rest of our codebase as
regards line length and comment standards.

There's one small difference with python vs the rest of the codebase when
it comes to API doc strings specifically. eg we have a docstring API comment
in python/qemu/machine.py:

class QEMUMachine:
     A QEMU VM.

     Use this object as a context manager to ensure
     the QEMU process terminates::

         with VM(binary) as vm:
         # vm is guaranteed to be shut down here

This formatting, including line breaks, is preserved as-is when a user
requests viewing of the help:


Help on class QEMUMachine in module qemu.machine:

class QEMUMachine(builtins.object)
  |  QEMUMachine(binary: str, args: Sequence[str] = (), wrapper: Sequence[str] 
= (), name: Optional[str] = None, test_dir: str = '/var/tmp', monitor_address: 
Union[Tuple[str, str], str, NoneType] = None, socket_scm_helper: Optional[str] 
= None, sock_dir: Optional[str] = None, drain_console: bool = False, 
console_log: Optional[str] = None)
  |  A QEMU VM.
  |  Use this object as a context manager to ensure
  |  the QEMU process terminates::
  |      with VM(binary) as vm:
  |          ...
  |      # vm is guaranteed to be shut down here
  |  Methods defined here:

IOW, while we as QEMU maintainers may not care about keeping to a narrow
line width, with API docstrings, we're also declaring that none of the
users of the python APIs can care either. These docstrings are never
reflowed, so they can end up wrapping if the user's terminal is narrow
which looks very ugly.

So this python API docstring scenario is slightly different from our
main codebase, where majority of comments are only ever going to be seen
by QEMU maintainers, and where C API doc strings don't preserve formatting,
because they're turned into HTML and re-flowed.

Having said all that, I still don't think we need to restrict ourselves
to 72 characters. This is not the 1980's with people using text terminals
with physical size constraints. I think it is fine if we let python
docstrings get larger - especially if the docstrings are already indented
4/8/12 spaces due to the code indent context, because the code indent is
removed when comments are displayed. I think a 100 char line limit would
be fine and still not cause wrapping when using python live help().

The trouble with long lines is not text terminals, it's humans.  Humans
tend to have trouble following long lines with their eyes (I sure do).
Typographic manuals suggest to limit columns to roughly 60 characters
for exactly that reason[*].

Most doc strings are indented once (classes, functions) or twice
(methods).  72 - 8 is roughly 60.

My problem with this patch isn't actually the docstrings -- it's one-line comments.

If you can teach flake8 to allow this:

# Pretend this is a single-line comment that's 73 chars

but disallow this:

# Pretend this is a two-line comment that's 73 chars,
# and continues to a new line that's also pretty long,
# and maybe keeps going, too.

I will happily accept that patch. Without the ability to enforce the style though, I am reluctant to pretend that it's even a preference that we have. I think it's a waste to hunt down and re-flow single-line comments that just barely squeak over a limit. They look worse.

We can discuss this more when we go to propose a style guide for the Python folder; I think it's maybe a misprioritization of our energies in the present context.

(I still have the style guide on my TODO list, and even began writing a draft at one point, but I think we'd both like to press forward on the Typing bits first.)

With nesting, doc strings can become indented more.  Nesting sufficient
to squeeze the doc string width to column 72 under roughly 60 is pretty
rare.  Going beyond 72 colums to keep such doc strings readable is
exactly what PEP 8 wants you to do.

Again, I see no reason to deviate from PEP 8.

[*] https://en.wikipedia.org/wiki/Column_(typography)#Typographic_style

reply via email to

[Prev in Thread] Current Thread [Next in Thread]