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/


    Capitalization:

        class names are CamelCase, while methods and members
        are_separated_by_underscores. This is not always possible,
        especially when subclassing from Qt. Everywhere else, this
        convention should be used. Qt signals are lowerCamelCase, to
        be consistent with Qt.

	Class members that are Qt objects themselves are probably OK
	being camelCase, but everything that's possibly public-access
	(through an API, for example), should be
	separated_by_underscores.



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.
