LazrStyleGuide

Not logged in - Log In / Register

Revision 5 as of 2010-04-28 13:05:52

Clear message

Style Guide for Lazr Projects

Lazr projects are a collection of the open-sourced stand-alone components that Canonical releases.

Lazr projects generally follow the guidelines described in the HackingLazrLibraries and Launchpad Hacking documents.

New projects should also always follow, and start from, the lazr.yourpkg template. Use the prepare.py script in the template package to get the package ready for development. For instance, if you want to make a lazr.foo package, you might do this.

bzr branch lp:lazr.yourpkg lazr.foo
cd lazr.foo
./prepare.py foo

See the Hacking document on where to go from there.

Package README.txt, docs, and tests

All documents in the package should use reStructuredText, with Sphinx extensions as needed. Try using bin/docs in your buildout's bin directory, and then looking at parts/docs/lazr.yourpkg/build/README.html.

The package's README.txt should be an introduction to the package.

If it gets too long (a precise definition of "too long" is TBD), strongly consider dividing up the document into a briefer introduction in the README.txt, linking (via Sphinx extensions) to documents in the docs directory.

On the other hand, if your package is very small, the README.txt may be the only documentation you need. In that case, delete the docs directory.

The README.txt and any/all documents in the docs directory are tested automatically by default (see tests/test_docs.py in lazr.yourpkg).

Doctests are encouraged. Additional unit-style tests should be added in the tests directory.

__version__ number

The __init__.py should have a __version__ string for the package that is used by setup.py for the packages version.

Guidelines for re-exporting

Sometimes a package wants to re-export code in its __init__.py file. For instance, if your package is essentially a module with tests and documentation, it may be quite ugly to have your users import your code with from foo.bar.bar import Bar. You would prefer to have your code canonically available as foo.bar.Bar.

However, the __init__.py should have a __version__, as described above; when the setup.py tries to import it, it may get an import error when it is trying to build. And coders looking at your package will generally not expect to find much code in your init.py file.

Our compromise is the following: