Content-Type: text/x-zim-wiki
Wiki-Format: zim 0.4
Creation-Date: 2014-07-31T21:06:39+02:00

====== Coding Style & Guidelines ======
Created Thursday 31 July 2014

See the python style guide for best practices. Some items to keep in mind:

* GUI classes are only allowed to construct widgets and wire signals. Any actual manipulation of pages, notebooks etc. should go elsewhere.
* Signal handlers have a method name starting with "do_" 
* Only use "assert" for checks that could be removed when code is stable, these statements could be optimized away
* Do not rely on ''__doc__'' on run time, this data could be optimized away
* Have a look e.g. at zim.parsing and zim.gui.widgets for common code snippets

**Other general guidelines**
* Writing test cases is good, full test coverage is better.  Run "./test.py --cover" to get a coverage report.
* Wait with loading modules and constructing widgets untill they are  really needed, this should keep startup speed reasonable
* Try to do slow operations that could be done asynchronous using the idle event or a thread, e.g loading the side pane index, or a list with search results, or even running an external command to check in a new version  of a file.

**Source code formatting**
* I use TABs (not spaces) with a tabstop set to the equivalent of 4 spaces, (most) lines should fit within 80 character with this setting.

**Documentation**
* Please add at at least docstrings for each public method with a short explanation what the method does. Docstrings should be formatted using the epydoc markup style, see: http://epydoc.sourceforge.net/
* There are a few custom fields used in the zim documentation:

	'''
	@signal: signal-name (param1, param2): description
	@emits: signal
	@implementation: must implement / optional for sub-classes
	'''
