diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/mailman/docs/STYLEGUIDE.rst | 44 |
1 files changed, 17 insertions, 27 deletions
diff --git a/src/mailman/docs/STYLEGUIDE.rst b/src/mailman/docs/STYLEGUIDE.rst index 1559580ca..31ece2296 100644 --- a/src/mailman/docs/STYLEGUIDE.rst +++ b/src/mailman/docs/STYLEGUIDE.rst @@ -8,53 +8,43 @@ Copyright (C) 2002-2016 Barry A. Warsaw Python coding style guide for GNU Mailman ========================================= -*NOTE*: The canonical version of this style guide can be found at: - -http://barry.warsaw.us/software/STYLEGUIDE.txt - This document contains a style guide for Python programming, as used in GNU -Mailman. `PEP 8`_ is the basis for this style guide so it's recommendations +Mailman. `PEP 8`_ is the basis for this style guide so its recommendations should be followed except for the differences outlined here. This document assumes the use of Python 3. -* After file comments (e.g. license block), add an ``__all__`` section that - names, one-per-line, all the public names exported by this module. See the - `GNU Mailman Python template`_ as an example. +* When creating new modules, start with the `GNU Mailman Python template`_ as + an example. + +* Names which should be imported by ``from-import`` should be added to + ``__all__`` but use the ``@public`` decorator from the top-level ``mailman`` + package to do this for all classes and functions. Constants and other + simple name bindings must be added to ``__all__`` explicitly. * Imports are always put at the top of the file, just after any module - comments and docstrings, and before module globals and constants, but after - any ``__all__`` definitions. + comments and docstrings, and before module globals and constants. Imports should be grouped, with the order being: - 1. non-from imports, grouped from shorted module name to longest module + 1. non-``from`` imports, grouped from shortest module name to longest module name, with ties being broken by alphabetical order. - 2. from-imports grouped alphabetically. + 2. ``from``-imports grouped alphabetically. -* In general, there should be one class per module. This is not a - hard-and-fast rule. Keep files small, but it's okay to group related code - together. List everything exported from the module in the ``__all__``. + Put a single blank line between the non-``from`` import and the + ``from``-imports. * Right hanging comments are discouraged, in favor of preceding comments. E.g. bad:: - foo = blarzigop(bar) # if you don't blarzigop it, it'll shlorp + foo = baz(bar) # This has a side-effect of fooing the bar. Good:: - # If you don't blarzigop it, it'll shlorp. + # This has a side-effect of fooing the bar. foo = blarzigop(bar) Comments should always be complete sentences, with proper capitalization and - full stops at the end. - -* Major sections of code in a module should be separated by form feed - characters (e.g. ``^L`` -- that's a single character control-L not two - characters). This helps with Emacs navigation. - - Put a ``^L`` before module-level functions, before class definitions, before - big blocks of constants which follow imports, and any place else that would - be convenient to jump to. Always put two blank lines before a ``^L``. + full stops (periods) at the end. We use two spaces after periods. * Put two blank lines between any top level construct or block of code (e.g. after import blocks). Put only one blank line between methods in a @@ -63,7 +53,7 @@ assumes the use of Python 3. * Try to minimize the vertical whitespace in a class or function. If you're inclined to separate stanzas of code for readability, consider putting a - comment in describing what the next stanza's purpose is. Don't put stupid + comment in describing what the next stanza's purpose is. Don't put useless or obvious comments in just to avoid vertical whitespace though. * Unless internal quote characters would mess things up, the general rule is |