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

[John Snow]

On 4/17/21 6:52 AM, Markus Armbruster wrote:
> John Snow <jsnow@redhat.com> writes:
> > On 4/16/21 8:44 AM, Markus Armbruster wrote:
> > > John Snow <jsnow@redhat.com> writes:

> > It will be an eventual thing, though: I think we need to agree on a
> > style guide document and in that same series, fix up the instances of
> > defying that guide. I think it's important to pair that work, because
> > the ease of finding and fixing those style deviations will help inform
> > how pragmatic the style guide is.
>
> Makes sense.
>
> The introduction of "sphinxy" doc strings (starting with commit
> adcb9b36c) may have been premature.

Somewhat premature, but what other format is there? It would have been 
worse to adopt Numpy or google style.

We'll dial it in over time, it will be fine.

> > I feel like it's something I want to do very soon, but not right now.
> > Maybe during the next freeze we can tackle it?
>
> Whenever you're ready.
>
> Until then, I feel we should try to minimize doc string churn.  Leave
> existing doc strings alone unless they're harmful.  Add new ones only
> when we believe they're helpful enough to justify some churn later.

OK. After the expr comments, I actually didn't add very many. I think I 
add one or two for the parser because I had trouble understanding at a 
glance how it worked, but most of the tiny functions and helpers I left 
alone.

I barely touched schema.py, because it was complex and I had some 
visions of refactoring it a little to make some of the typing better later.

> > > Improvement, but mind PEP 8's "You should use two spaces after a
> > > sentence-ending period in multi-sentence comments".
> >
> > How important is this, and why? My existing prejudice is that it's only
> > a superficial detail of writing with no real impact.
>
> Holy wars have been fought over less.

:)

> > (Of course, a single space typist WOULD believe that, wouldn't they?
> > Those single-space typists are all the same!)
>
> I offer three reasons:
>
> * Local consistency
>
> * Stick to PEP 8 unless you have good reason not to.
>
> * It makes Emacs sentence commands work by default.

For me, it's another thing in the category of "I don't actually mind 
either way", and can foresee myself accepting a patch using either style 
without comment. Inconsistency here doesn't really bother me unless it's 
inconsistent within a single docstring.

For QAPI, since you're the maintainer, I can adhere to your style. For 
the purposes of all Python code, though, I am not sure I want to bother 
enforcing it myself.

You're always welcome to post-edit anything I've written for 
typographical consistency as you see fit, I genuinely won't mind. (It 
saves me the trouble of having to copy-edit for something I am visually 
blind to.)

That said, I'll try to match your preferred style for QAPI at a minimum. 
I notice that emacs' reflow command does not always insert two spaces if 
a paragraph already sneaks in under the column limit; is there a way to 
*force* it to add two spaces?

> > Unfortunately, omitting it from flake8 means I'll probably also miss
> > cases where I or someone else have gone slightly over the limit for
> > docstrings, and doubt it will be enforced consistently.
>
> I'm happy to correct the occasional minor style issue manually.

If you accept that burden then I have no leg to stand on, I suppose :)

> > > 1.2. you may drop it.  I can pick it up and take care of it.
> >
> > This one, please!
>
> You got it.

Thanks! You can do that whenever, it won't interfere with anything in 
the interim.

--js