Hacking

There may only be a handful of people working on QuuxBox at the moment, but that number may increase in time. So, with thought towards the future and also for the sanity of current developers, the following coding style rules are proposed. These rules should be followed at least for system API work that many developers will need to lose. Application developers may also want to follow them, but for them its not as important.

Source File Layout

Files should be identified with at least their name, author, and function at the top of the file in comments clearly set out from the source code. Also, the CVS Id field should be added to all source files since it can be useful in merging changes from outside CVS. Proposed is a simple format that marks id, filename and author with labels followed by a colon and content in comments at the beginning of the file. The author's name should include an e-mail address. A description of the file's purpose and general structure should follow the comments block in a Doc string, which may be used by pydoc to build documentation. An Example is given.


# $Id: hacking.xml,v 1.1 2003/02/17 18:23:34 ssaville Exp $
# File: Apps/Ex/Examples.py
# Project: QuuxBox
# Author: Stephen Saville (ssaville@uiuc.edu)
"""Examples introducing the layman to QuuxBox.
...
"""

Indentation

As we all know, indentation is very important in Python, where blocks are delimited by whitespace. Therefore, to prevent simple bug fixes from causing python to spew IndentationError exceptions all over the place, its important for everyone to follow the same indentation practice. First, note that no source file in QuuxBox should ever contain the tab character. This is very important! Each indentation level should be set off with four spaces. To make vim do this, run the following commands when you start editing files and hitting the tab key will "do the right thing."

:set ts=4
:set sw=4
:set et
:set sts=4

You may want to add those commands to ~/.vimrc so you don't forget to execute them every time you start vim. One of those emacs people can lisp some instructions for that program after they're done waiting for it to start up.

Naming Scheme

For the sake of building a uniform API, its good to follow some standard naming scheme for functions, especially those defining the public interface for a program or library. Due to its overwhelming popularity in object-oriented programming circles and exquisite aesthetic values, we'll be using a Java-style initial lowercase naming scheme. Function names should start with a lower case letter and contain only alphabetic characters. Additional words in the function name should begin with a single capitol letter. Also, functions that are meant to get or set attributes of an object should be prefixed with get- or set- followed by a word starting with a capitol letter. Optionally, programmers may want to flag private attributes/methods of an object instance by beginning them with an initial underscore. An example follows.


class Example:
    def __init__(self, name, data=None):
        self._name = name
        self._data = data

    def getName(self):
        return self._name

    def getData(self):
        return self._data

    def setData(self, data):
        self._data = data

    def printSelf(self):
        print "%s: %s" % (self._name, self._data)

Documentation Strings

All functions meant for public consumption should be documented with a Doc string. For the uninitiated, in python a Doc string is a string placed directly after the formal declaration of a function or class before any other code. Standard python practice dictates that the string should begin with a single sentence containing a terse description of the function, class, or module followed by a blank line and then any additional explanation. We will follow this practice with one exception -- in between the initial description and the explanation should be an argument pattern giving the types of arguments accepted by the function. See IPC/System.py for examples of this format.