[Openstack] Being pedantic about pedanticism: HACKING styleguide
Jay Pipes
jaypipes at gmail.com
Thu Mar 22 21:13:53 UTC 2012
(in a thundering voice)
Release the Kraken!
On 03/22/2012 12:22 PM, Andrew Bogott wrote:
> Just now I set out to merge a recent style guide change from
> python-novaclient into the hacking docs of other OpenStack projects. My
> patch didn't apply, though, because each project has subtly diverging
> HACKING files.
>
> Rather than contribute to this divergence, I've now read and compared
> the style guides from Nova, Glance, Keystone, python-keystoneclient, and
> python-novaclient. From these diffs I've created a file (attached) that
> encompasses the total of all guidelines from all projects. Remarkably,
> this merge produced only minor disagreements, described below under the
> heading FLAMEBAIT.
You missed a couple things :) See below.
> I propose that this unified style guide be copied into each of the above
> projects, with a mandate to maintain consistency henceforth. Any
> objections?
Yes. See below.
> -Andrew
>
> FLAMEBAIT (docstring format):
>
> The only explicit contradiction I came across is regarding docstring
> formatting. Glance says this:
>
> **DO NOT** leave an extra newline before the closing triple-double-quote.
Yes, and there's a reason. The extra newline was an anachronism from
Emacs of Old and is pointless -- it does nothing to improve readability.
> Nova, this:
>
> A docstring ends with an empty line before the closing quotations.
>
> I propose that we just pick one or the other, or remove both prescriptions.
Well, you know which one I'm partial to. :)
> FLAMEBAIT (filename):
>
> Some projects have a HACKING file, and some have a HACKING.rst file.
> Doesn't .rst generally indicate a REST API definition? I propose that
> the file be called HACKING.
I changed the Glance HACKING to HACKING.rst when I saw a couple of the
other projects do so... I could go either way.
Here are some of the other things you missed that are important differences:
Docstrings
==========
Glance's HACKING section on docstrings includes these:
Docstrings should ONLY use triple-double-quotes (``"""``)
Single-line docstrings should NEVER have extraneous whitespace
between enclosing triple-double-quotes.
**INCORRECT** ::
""" There is some whitespace between the enclosing quotes :( """
**CORRECT** ::
"""There is no whitespace between the enclosing quotes :)"""
Nova's HACKING section on docstrings also states that a docstring's
one-line summary should end in a period, and that multi-line docstrings
should always have a one-line summary, less than 80 characters, also
ending in a period.
Glance's section on docstrings doesn't have this, as I believe that the
rule on periods stretches the level of pedantry to new levels.
Object Imports
==============
In addition, the following DOES NOT appear in Glance's section on imports:
- Do not import objects, only modules
Nowhere in PEP8 does it mention anything about not importing objects. In
fact, PEP8 says this:
<pep8>
Imports should usually be on separate lines, e.g.:
Yes: import os
import sys
No: import sys, os
It's okay to say this though:
from subprocess import Popen, PIPE
</pep8>
In fact, many successful projects, including Django make use of
importing objects instead of modules, so I don't see the need for that rule.
Best,
-jay
More information about the Openstack
mailing list