Code Styleguide

Here is the code styleguide each core plugin and component has to obey.

Python

The pocoo codestyle is defined in PEP 8.

The code has to work with Python 2.4, so don't use features from Python 2.5. If there is a feature in Python 2.5 which is backportable, you can add a file to source:/pocoo/trunk/pocoo/utils.

Here are the rules in short:

Naming

class MyClass(object): pass

def my_function_or_method(arg): pass

def myFactoryFunction():
    class Foo(object):
        pass
    return Foo

variable = 42
long_variable_name = 'Spam'

Indent and Line Length

Everywhere 4 spaces, no tabs (nowhere, in code or data) and maximal line length is 90 chars.

Use parentheses to avoid "\":

if some_variable == other_variable and my_variable > your_variable:
    print 'Wohooo'
elif ((some_variable == my_variable and other_variable < your_variable) or
      some_variable == your_variable):
    print 'Wicked'

Spacing

• No spaces directly within brackets/parentheses and when calling or subscripting: foo(x, y)
• No space before, one after the comma
• No space around = in keyword arguments
• Usually spaces around operators and assignments
• Two empty lines after class or toplevel function definitions
• One empty line after classes' docstrings
• One empty line between classes' methods, if they are not very short

Docstrings

At least classes must have docstrings. Toplevel function should have them, too. Methods only if their purpose can't be recognized from a single look.

Docstrings must be formatted using ReST, as they are processed by epydoc to produce API docs.

Docstrings for global variables and attributes:

#: This is the docstring.
#: It can have multiple lines.
variable = 'value'

Javascript

The Javascript style is like the normal Java style just with 2 space indent.

Naming

mypackage = {
  method : function() {}
}

MyClass = function() {}

function myMethod(arg) {}

var variable = 42
var longVariableName = 'Spam'

So. CamelCase and smallCase everywhere except short variables which are of course just lowercase :D

JQuery Notation

For JQuery we use this style:

$('div').hide();
$('.active').html('Test')
            .addClass('test')
            .show()
$('div').$each(function(e) {
  e.show();
});

Javascript Package System

JavaScript files use a simple package structure. Pocoo automatically adds an object called Pocoo to the global namespace. All pages should just modify that specific namespace, not any other. there is no body onload, just $(document).ready(function(){}). The package namespace is flat, thus no Pocoo.Lib.Bar etc. If you have multiple functions wrap them in a closure or add one new object (like Pocoo.ViewTopic), but not one level more.

Jinja Templates

Jinja templates should produce valid xhtml 1.0 output and use a 2 space indent.

File headers

All Python files must have a file header conforming to the following spec:

# -*- coding: utf-8 -*-
"""
    pocoo.subpackage.module
    ~~~~~~~~~~~~~~~~~~~~~~~

    Short description of what the module contains.


    Long module docstring heading (optional)
    ========================================

    Docstring contents...

    :copyright: 2006-2007 by Author, Author, Author.
    :license: GNU GPL, see LICENSE for more details.
"""

(if the file should be executable as a script, add #!/usr/bin/env python to the top.)

In case of Javascript files, the header looks like this:

/**
 * Pocoo DOM library
 * ~~~~~~~~~~~~~~~~~
 *
 * A library for manipulating DOM elements.
 *
 * :copyright: 2006 by the Pocoo team.
 * :license: GNU GPL, see LICENSE for more details.
 */

Code style helpers

Two helper scripts exist for checking and maintaining good code style.

• source:scripts/check_sources.py (can be called via make check in the source root) checks the sources for correct file headers, indentation and common coding glitches.
• source:scripts/reindent.py (can be called via make reindent) reindents all files according to our style (converts tabs, removes trailing whitespace).