3.2. Comments. Documenting Code

3.2.1. Module documention

Always insert some lines of description of the module, containing at least the author and one line of short explanation. Remember that a lot of people might have to read and understand your code. Document as much as possible. Add example code how to use the module where possible and necessary. Please insert the following template at the beginning of the file:

#############################################################################
# ModuleName - one line explanation             
# verbose documentation, example code
# @author: author name                                                       
# @copyright: author                                                            
# @license: GPL (details at http://www.gnu.org)                                 
# @dependencies: any libs / program versions the module might depend on       
#                                                                               
# @TODO:        
#############################################################################
    	

A changelog will be appended automatically to every file using comments supplied when commiting changes to the CVS.

3.2.2. Docstring documention

Try to always insert at least one line of docstring unless the function is no more than a couple of lines long and perfectly self-explanatory.

3.2.3. COMMENTS

Mark places that need fixing with a comment like this:
# FIXME: a comment on what should be fixed how
... your code ...