[Gzz] PEG coding_standard--vegai: Coding Standard (revised)

[Vesa Kaihlavirta]

=============================================================
PEG coding_standard--vegai: Coding Standard
=============================================================

:Author:   Vesa Kaihlavirta
:Last-Modified: $Date: 2003/02/04 18:46:12 $
:Revision: $Revision: 1.12 $
:Status:   Incomplete
:Scope:    Minor
:Type:     Policy

Our coding standard (/gzz/CODING) requires revising, mainly because of the
large and growing amount of python code.

Issues
======

- our \*.java have the license attached to every file. Is that necessary?

    RESOLVED: Yes, according to FSF.

- should we have automatic tests for enforcing parts of the standard?

    At least for the most trivial ones (rcsid, tab check, imports, class 
names).
    Failing tests will clearly tell what the developer did wrong.

- should the rcs id variable be "rcsid" or "rcsId" ?

    RESOLVED: rcsId, adhering to rule 9.

- should all code and data really be in classes? If so, why?

    RESOLVED: No. Rule 6 modified to catch the idea better.

- should Tabs be allowed or not?

    RESOLVED: a conversion tool at "make committable" will
    convert tabs into 8 spaces

- import grouping is not resolved

Changes
=======

These apply to all \*.py (and possibly \*.test).

1. Header comments should include full module name of the file (eg.
   gzz/modules/pp/demotest.py would have gzz.modules.pp.demotest).

2. Header comments should include authors.

3. After header comments, rcsid:
   rcsid = "$Id: peg.rst,v 1.12 2003/02/04 18:46:12 Vegai Exp $"

4. After rcsid, the imports (unless there's a good reason to delay
   importing).

   - Prefer "import foo" to "from foo import bar".
   - Prefer "from foo import bar" to "from foo import \*".
   - No more than one import package in one line, except when importing gzz
     and java::

        import os, sys   # Preferably no.

        import os        # Yes.
        import sys

        import gzz, java # Yes.


5. Imports should be grouped in the following order:

   - standard python imports
   - 3rd party python imports
   - java imports
   - gzz imports

   * imports should be in alphabetical order in the groups
   
6. Code should be structured so that it can be imported and re-used, for 
example by
   putting state in classes instead of the module namespace. Executable code
   in module namespace is discouraged -- except for "if __name__=='__main__':"

7. Class names are CapitalizedWords.

8. Class methods and attributes are mixedCase.

9. Functions and variables are mixedCase.

10. Tab-size is 8 (will be converted to spaces by make committable), 
indentation
    at 4 spaces.

11. Never use tabs.


Notes
=====

- items 8-12 are arbitrary choices for the sake of consistency

- "A Foolish Consistency is the Hobgoblin of Little Minds" - Ralph Waldo 
Emerson


References
==========

http://www.python.org/doc/essays/styleguide.html
http://www.python.org/peps/pep-0008.html
http://www.wikipedia.org/wiki/CamelCase