Format
Avoid tabs at all costs. Python is whitespace sensitive. Use two spaces for an indent.
Use Unix line endings. See the section on line endings below.
Mind the 80 character print margin. Insert hard line breaks to wrap lines past 80 characters long. It makes CVS diffs and ViewCVS listings of code in fixed fonts easier to read. It also makes reading code in an editor, a console, or even on paper more bearable as you won’t have to scroll horizontally to read long lines or watch them make ugly wraps.
Design
ClassNames, methodNames, functionNames, variable_names, SIMPLE_CONSTANTS. Remember, everything is an object. This naming convention makes distinguishing named references easier.
Avoid Python private_attributes. They are truly private, not protected, and necessitate a name change whenever a subclass needs to access them. Keep in mind private attributes are different from special methods like __init__ and __str__. Use those anytime.
Initialize instance and module variables. Set them to default values (e.g. None) in class constructors or as close to the top of a module as possible.
Make large modules packages. If a Python module (single .py file) in the top level source directory grows a number of large classes, consider refactoring it into a Python package (folder with an __init___.py and many .py modules).
Conform to the following data hiding rules. None of these are enforced by the language, but they will be by your fellow LSR developers.
- All instance variables are considered protected (i.e. accessible within a class and its subclasses only). The exception is when there is a @note saying that the class is struct-like and its attributes can be accessed directly (e.g. POR).
- Methods that begin with a single underscore are considered protected.
- All other methods are considered public.
Module variables are considered private. The exceptions are SIMPLE_CONSTANTS that are considered global, but read-only.
If access to an instance variable is needed outside its containing class, define get and set methods to expose it (e.g. getParent, setParent).
- If access to a module variable is needed outside that module, define top level functions to expose it.
Do not define a Python property(fget, fset) without good reason. It will be easily confused with an instance variable.
Documentation
Write valid epydoc comments. See http://epydoc.sourceforge.net/epytext.html for help with epydoc syntax. Review the log after epydoc HTML generation for errors.
Mention things todo, warnings, notes, and deprecations. Include the @todo, @warning, @note, and @deprecated fields in epydoc strings to call out important comments for developers in the generated epydoc. Search for @todo: YOUR INITIALS: SOME COMMENT in your editor to find code that needs work. For instance, @todo: PP: comment this code.
Note keyword arguments if possible. If a set of keyword arguments will always be the same, note them using the epydoc @keyword field. It works just like a @param field, but does not require the parameter to be named explicitly in the arguments to a function or method.
Give credit. Add the names of other authors and contributors to the source file headers by adding additional @author lines.
Fix errors reported when generating documentation. Keep the documentation valid and up-to-date. We typically take a week to do this just before a release.
Miscellaneous
Fix problems as you edit modules. If you plan on making edits to a file and notice problems with respect to these guidelines in this file, correct the mistakes.
