Coding Conventions for VisTrails
--------------------------------------------------------------------------------

Variable naming, spacing
------------------------

Long version:

    http://www.python.org/dev/peps/pep-0008/


Short version:

    Use 4 spaces per indentation level.

    Use spaces, not tabs. 

       Hint: if you have a file that uses tabs and you're using emacs:

       M-x mark-whole-buffer
       M-x untabify

    Limit lines to 79 characters. (Use Python's implied continuation
    for parentheses, brackets and braces. Or use a backslash):

       if this_is_true and this_other_thing_is_also_true and this_other_thing_makes_this_line_too_long:
           raise This_is_bad_style

       Fix it like this:

       if (this_is_true and
           this_other_thing_is_also_true and
           this_other_thing_makes_this_line_too_long):
           raise This_is_better_style

       Or like this:

       if this_is_true and \
          this_other_thing_is_also_true and \
          this_other_thing_makes_this_line_too_long:
          raise This_is_not_as_good_but_better_than_long_lines

    Blank lines

        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 a
        bunch of related one-liners (e.g. a set of dummy
        implementations). Use blank lines in functions, sparingly, to
        indicate logical sections.

    Whitespace

        Learn by example:

        Yes: spam(ham[1], {eggs: 2})
        No:  spam( ham[ 1 ], { eggs: 2 } )

        Yes: if x == 4: print x, y; x, y = y, x
        No:  if x == 4 : print x , y ; x , y = y , x

        Yes: spam(1)
        No:  spam (1)

        Yes: dict['key'] = list[index]
        No:  dict ['key'] = list [index]

        Yes:  def complex(real, imag=0.0): return magic(r=real, i=imag)
        No:   def complex(real, imag = 0.0): return magic(r = real, i = imag)


    Comments:

        Read http://www.python.org/dev/peps/pep-0008/



Docstrings
----------
    We agreed using something a little more compact than the guidelines
available at:
    http://www.python.org/dev/peps/pep-0257/

    Examples:
    If it is an obvious function, we should use something like this:
    def temporaryDirectory():
        """ temporaryDirectory() -> str 
         Returns the path to the system's temporary directory """
         return "/tmp/"
    

    If the function has structured parameters requiring a detailed description,
    use something like this:
    
    def complex(real=0.0, imag=0.0):
        """complex(real=0.0, imag=0.0) -> complex
        Form a complex number.

        Keyword arguments:
        real -- the real part
        imag -- the imaginary part

        """
        if imag == 0.0 and real == 0.0: return complex_zero
        ...
        

Importing modules
-----------------

    Please import the modules using the fully qualified names,
    even if they are in the right directories. For example, if you
    have a file inside vistrails/core that imports a module inside 
    vistrails/core/data_structures, do NOT use this

    import data_structures.graph     # WRONG, don't do it!

    instead, say

    import core.data_structures.graph   # RIGHT

    This allows us to run the modules as standalone classes, which is
    good for testing purposes.

    Don't use the construct "from foo import *". This also imports the
    tests from that module. The problem is that the test suite then
    runs these tests twice. But worse than that is the problem that a
    module that imports tests from other modules now reports these
    tests as its own, even though it might have none. This gives us a
    false sense of test converage which should be avoided.
