CodeFormatting

Code Formatting Guidelines

Consistently formatted code enhances readability, reusability, and longevity of code, which is a good thing, especially considering the effort (and expense) that goes into writing code in the first place. This document provides some basic guidelines for the formatting of code developed on this project.

General

• Document the code. No exceptions.
• It is generally a good idea to indicate the authors of the code (usually in the comment block for the file). This is especially helpful a couple years from now when trying to determine why something is implemented a particular way or to find the expert on the issue being examined.
• Write unit tests.
• Set your editor to use UTF-8 by default.
• Always at least make a list of external dependencies (libraries, tools, applications) and where to find them (if not included in version control).
• Avoid OS specific dependencies. If really necessary, always make a note of any OS specific dependencies introduced by a block of code, and always implement such a block in a way that replacing with another block that might be developed in the future would be a relatively trivial matter (e.g. don't embed a bunch of win32 specific calls throughout the code- write an abstraction layer instead).

Python

The Style Guide for Python Code (PEP-0008) should be followed for all Python code, with the following exceptions:

• indentation should use 2 spaces, not 4 as suggested by Guido and Barry. One space is too short, and four leads to a greater likelihood of having to split lines.
• Never use tabs for indenting. Set your editor to use soft tabs or replace tabs with spaces.
• Leave two blank lines between method definitions inside a class.
• If adding multiple classes in a file, separate them with a commented row of "="
• To be more consistent with the Java conventions, use the suffix "Exception" (rather than "Error" as suggested in PEP-0008) when naming exceptions.
• Follow DocString conventions to document code. Use either the EpyDoc or Sphinx approaches, but do not mix them within the same application. In general, using Sphinx autodoc is the preferred approach and will produce cleaner documentation than JavaDoc. This implies using reStructuredText formatting conventions in the docstrings. Documenting Python provides an overview of using Sphinx for documenting python.