
========================
Elisa coding guidelines
========================

Basically we (try to) stick with recommendations from the `PEP 8`_ for
coding style and `PEP 257`_ for docstrings.

.. note::

   Don't hesitate to complete :-)

Naming conventions
==================

- Package and module names should be all lower-case, words may be
  separated by underscores.
- Class names use CamelCase, example: `PlayerPlugin`
- The names of functions, variables and class members use all
  lower-case, with words separated by underscores, example:
  `toggle_pause`
- Class method names use CamelCase
- Variables representing user defined types use CamelCase
- Internal methods and variables are prefixed with a single
  underscore, example `_do_something_internal`
- Instance properties used by external components may use
  property_name__{get,set} helper methods if more than handling a
  variable value is needed
- Never name a variable ``_``

Miscellaneous
=============

- Code indentation: use 4 spaces. Tabs not allowed :)
- Lines shouldn't exceed a length of 80 characters.
- Use `raise SomeException("message")` instead of `raise
  SomeException, "message"`
- only *one* return per function/method
- Commit messages should always contain the corresponding ChangeLog
  entry. Use of data/cl.pl ChangeLog-updater script is recommended.


.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
.. _PEP 257: http://www.python.org/dev/peps/pep-0257/
.. _ReST: http://docutils.sourceforge.net/docs/ref/rst/directives.html
.. _Epytext: http://epydoc.sourceforge.net/epytext.html
