openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

(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