← Back to team overview

openstack team mailing list archive

Re: Being pedantic about pedanticism: HACKING styleguide


(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

Yes. See below.


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:


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.


  """ 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:

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

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.


Follow ups