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

:Revision: $Revision: 1259 $
:Date: $Date: 2007-01-03 16:30:26 +0100 (mer, 03 jan 2007) $


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`
- Class names inheriting from ``core.component.Interface`` use mostly
  CamelCase, but are prefixed by an "I" letter, example: `IDataAccess`
- 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
- Internal methods and variables are prefixed with a single
  underscore, example `_do_something_internal`

Internationalization
====================

Every string displayed on Elisa's window should be translatable using
the ``_`` function like this: ::

  menu_name = _("My new plugin")

Every time you add a new call to ``_()`` please update the elisa.po
file using the following command:

::

  $ xgettext -o po/elisa.po -L Python `find elisa/core -name "*.py" -print`

Translators can then use that file to provide elisa translation in a
new language.

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"`
- ReST_ would be the preferred format for documentation, although
  WikiFormat wouldn't hurt too much
- Commit messages should always contain the corresponding ChangeLog
  entry. Use of cl.pl ChangeLog-updater script is recommanded.



.. _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
