Discussion of Coding-Style
==========================

Participants
------------
- Dumitru
- Fred
- David
- Olivier D [leader]

Existing Python coding style specifications and guidelines
----------------------------------------------------------

    * http://www.python.org/dev/peps/pep-0008/
    * http://www.python.org/dev/peps/pep-0257/
    * http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
    * http://www.voidspace.org.uk/python/articles/python_style_guide.shtml
    * http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
    * http://www.cs.caltech.edu/courses/cs11/material/python/misc/python_style_guide.html
    * http://barry.warsaw.us/software/STYLEGUIDE.txt
    * http://self.maluke.com/style
    * http://chandlerproject.org/Projects/ChandlerCodingStyleGuidelines
    * http://lists.osafoundation.org/pipermail/dev/2003-March/000479.html
    * http://learnpython.pbworks.com/PythonTricks
    * http://eikke.com/how-not-to-write-python-code/
    * http://jaynes.colorado.edu/PythonGuidelines.html
    * http://docs.djangoproject.com/en/dev/internals/contributing/#coding-style

We will probably want to take PEP-8 as starting point, and read what other
people think about it / how other coding guidelines differ from it.

Dumi: we should also try to find tools that automate these
processes: pylint, pyflakes, pychecker, pythontidy

OD: I think PEP8 + Google guidelines are a good basis.
OD: Things about PEP 8 I don't like (but it may be just me):

   * If necessary, you can add an extra pair of parentheses around an
     expression, but sometimes using a backslash looks better.
    --> I rarely find that backslash looks better. In most situations you can
        get rid of them. Typically I prefer:
            if (cond_1 and
                cond_2 and
                cond_3):
        to
            if cond_1 and \
               cond_2 and \
               cond_3:

   * You should use two spaces after a sentence-ending period.
    --> Looks weird to me.

   * Imports should usually be on separate lines
    --> Can be a lot of lines wasted for no obvious benefit. I think this is
        mostly useful when you import different modules from different places,
        but I would say that for instance for standard modules it would be
        better to import them all on a single line (doing multiple lines only
        if there are too many of them), e.g. prefer:
            import os, sys, time
        to
            import os
            import sys
            import time
        However, I agree about separating imports between standard lib / 3rd
        party, e.g. prefer:
            import os, sys, time
            import numpy, scipy
        to
            import numpy, os, scipy, sys, time
        (Personal note: preferably order imports by alphabetical order, makes
         it easier to quickly see if a specific module is already imported,
         and avoids duplicated imports)

    * Missing in PEP 8:
        - How to indent multi-line statements? E.g. do we want
            x = my_func(a, b, c,
                d, e, f)
          or
            x = my_func(a, b, c,
                        d, e, f)
          or
            x = my_func(
                a, b, c, d, e, f)
          --> Probably depends on the specific situation, but we could have a
            few typical examples (and the same happens with multi-lines lists)

    * From PEP 257: The BDFL [3] recommends inserting a blank line between the
      last paragraph in a multi-line docstring and its closing quotes, placing
      the closing quotes on a line by themselves. This way, Emacs'
      fill-paragraph command can be used on it.
     --> I have nothing against Emacs, but this is ugly!

Documentation
-------------

How do we write doc?

Compatibility with various Python versions
------------------------------------------

    * Which Python 2.x version do we want to support?

    * Is it reasonable to have coding guidelines that would make the code as
compatible as possible with Python 3?

C coding style
--------------

We also need a c-style coding style.

Meetings
--------

   * Thursday 2010/09/09, 11 am