Coding Style

Like most Python projects, we try to adhere to  PEP 8 (Style Guide for Python Code) and  PEP 257 (Docstring Conventions). Be sure to read those documents if you intend to contribute code to ObsPy.

Reference Conventions

As with numpy.ndarrays or Python lists, we try to reduce the memory consumption by using references where ever possible. In the following example a is appended to b as reference, that is the reason why b get changed when we change a:

>>> a = [1,2,3,4]
>>> b = [5,6]
>>> b.append(a)
>>> a[0] = -99
>>> print b
[5, 6, [-99, 2, 3, 4]]

Import Conventions

Like the Python projects NumPy, SciPy and matplotlib, we try to improve readability of the code by import the following modules in an unified manner:

• import numpy as np
• import matplotlib.pylab as plt

Naming Conventions

• Package and module names should be all lower-case, words may be separated by underscores.
• Class names use CamelCase
  e.g. DatabaseManager
• The names of functions are written in mixedCase (differs from CamelCase by initial lowercase character!)
  e.g. deleteXMLResource
• Variables and class members use all lower-case, with words separated by underscores
  e.g. access_log_file
• Internal methods and variables are prefixed with a single underscore
  e.g. _my_private_var or _myPrivateMethod

Doc Strings

• one liner: both """ are in new lines

    def test():
        """
        This is a one line doc string.
        """
        echo "test"
  

• multiple lines: both """ are in new lines - also you should try provide a meaningful one-liner description at the top, followed by two linebreak with further text.

    def test():
        """
        This is a much longer doc string which won't fit in one line. 
  
        Therefore we have to break lines.
        """
        echo "test"
  

Miscellaneous

• Lines shouldn't exceed a length of 79 characters.
  No, it's not because we're mainly using VT100 terminals while developing, rather because the diffs look nicer on short lines, especially in side-by-side mode.
• never use multiple statements on the same line, e.g. if check: a = 0.
• Prefer list comprehension to the built-in functions filter() and map() when appropriate.

Tests

• tests which are expected to fail, cause there is a known/unfixed bug should be commented with an XXX followed by an valid ticket number, e.g.

    def test_fails():
        """XXX: This test does something. 
  
        But fails badly. See ticket #number.
        """
        echo "test"
        ...
        # XXX: here it fails
        ...