Skip to content

Latest commit

 

History

History
109 lines (81 loc) · 3.45 KB

GUIDELINES.rst

File metadata and controls

109 lines (81 loc) · 3.45 KB
Raw

Development Guidelines

The following are the practices that have evolved over the course of :term:`FiPy`'s development. Stray from them at your peril.

Object Oriented Design

Multiple inheritance is forbidden.

Programming Style

To the greatest extent possible, we follow PEP 8. We make the following exceptions because we had already written a great deal of code before we knew there even was a PEP 8.

Maximum Line Length

The preferred place to break around a binary operator is before the operator, not after it. Some examples:

class Rectangle(Blob):

    def __init__(self, width, height,
                 color='black', emphasis=None, highlight=0):
        if (width == 0 and height == 0
            and color == 'red' and emphasis == 'strong'
            or highlight > 100):
            raise ValueError("sorry, you lose")
        if width == 0 and height == 0 and (color == 'red'
                                           or emphasis is None):
            raise ValueError("I don't think so -- values are %s, %s"
                             % (width, height))
        Blob.__init__(self, width, height,
                      color, emphasis, highlight)
Package and Module Names
Use mixedCase rather than all-lowercase names.
Function and Method Names
Use mixedCase rather than lower_case_with_underscores names.

Any other deviations from PEP 8 should probably be corrected, but ask if you are unsure. Even the exceptions listed above are open to discussion by anybody willing to do the work of changing the existing code.

Testing

:term:`FiPy` uses :mod:`doctest` pervasively. We have not seen a case where :mod:`unittest` would simplify things. As a heavily numerical code, care must be taken in checking floating-point values.

Tests should not fail as a result of a missing optional install. :term:`FiPy` defines the following :mod:`doctest` directives to specify what conditions are needed to run the test:

GMSH
The :program:`gmsh` executable, version 2.0 or greater, must on the :envvar:`PATH`.
SCIPY
The :mod:`scipy` package must be importable.
TVTK
The :mod:`tvtk` (or :mod:`enthought.tvtk`) package must be importable.
SERIAL
:term:`FiPy` must be running on a single processor.
PARALLEL
:term:`FiPy` must be running on more than one processor.
PROCESSOR_0
Whether serial or parallel, the test will only be run on processor ID 0.
PROCESSOR_0_OF_2
The test will only be run on processor ID 0 of a two processor parallel job.
PROCESSOR_1_OF_2
The test will only be run on processor ID 1 of a two processor parallel job.
PROCESSOR_0_OF_3
The test will only be run on processor ID 0 of a three processor parallel job.
PROCESSOR_1_OF_3
The test will only be run on processor ID 1 of a three processor parallel job.
PROCESSOR_2_OF_3
The test will only be run on processor ID 2 of a three processor job.
LSMLIB
The :mod:`lsmlib` package must be importable.

Further directives can be defined using :func:`~fipy.tests.doctestPlus.register_skipper`. These definitions should be placed in the file to which they pertain, e.g., GMSH is defined in :file:`fipy/meshes/gmshImport.py`.