Coding conventions for PyBaz Editor: David Allouche * Introduction Good code must look good. You can recognize bad code from its shape. Pretty code is enjoyable to read, edit and debug. Pretty code is easy to process by automated tools. While all those statements may not always be true, please just suspend your disbelief :-) Code that does not conform to the following style rules will be edited at some point to make it conformant. That is the kind of change which can cause needless merge conflicts, thus causing us all displeasure. Some of the code I have written may not conform to these recommandations, generally it should be fixed. * Bazaar Usage Bazaar is the versioning system used for the development of PyBaz, that is only fair since PyBaz implements Python bindings for Bazaar. All source files must use taglines. New files should use taglines generated by the uuidgen program. Taglines containing english text (like a short descrition of the file) are forbidden. Pure text files which may be printed (like this one or the README file) can use explicit ids. * Pychecker All source files must be valided using PyChecker. The check.py script sets the appropriate suppressions and load all modules. To override any suppressions defined in "~/.pycheckrc", check.py sets HOME to the current directory, which is expected to be within the pybaz source tree. That means you should not run check.py from within your home directory. (If you have a better way to do that, you are welcome). * General Conventions The base for the PyBaz coding conventions are the following PEP documents: PEP 8 -- Style Guide for Python Code http://www.python.org/peps/pep-0008.html PEP 257 -- Docstring Convention http://www.python.org/peps/pep-0257.html You should start by reading those references. This document will only describe differences from the conventions described in these documents and repeat a few important conventions. * Naming Conventions Class names must use MixedCase. As an exception, iterator classes must be named as functions because they are used in the same way as functions returning a sequence. Function and method names must use lowercase_with_underscore for long names (e.g. exec_safe_status_stdout). Lowercase without separator _may_ be used for short names. When in doubt, use underscore separated names. Variable names obey the same naming conventions as function and method names. One letter variables are allowed when the variable is only used very locally. Never use the characters `l' (lowercase letter el), `O' (uppercase letter oh), or `I' (uppercase letter eye) as single character variable names. In some fonts, these characters are indistinguisable from the numerals one and zero. When tempted to use `l' use `L' instead. * Text width The text must fit in 79 columns. If it makes it look better, it may be wrapped on fewer columns (e.g. 70). The first line of "class" and "def" statement must fit in 76 columns, so emacs outline mode has room for an ellipsis. * Whitespace Separate top-level function and class definitions with two blank lines. Method definitions inside a class are separated by a single blank line. Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between related one-liners. When blank lines are used to separate method definitions, there is also a blank line between the `class' line and the first method definition. Class statements defining a property may be placed immediately after the methods used by the property, without intervening blank lines.