Code styling guidelines

Hacking on Tor2Web-3.0

This documents gives guidelines on where to start looking for helping out in developing on Tor2Web-3.0 and what guidelines you should follow when writing code.

General information about this section can be found in [GLBackend documentation wiki](

Python funnyties

We try to follow the general python best practices and styling guides as specified in PEP.

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
    Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Tim Peters, The Zen of Python

Style guide

This is an extract of the most important parts of PEP-8. When in doubt on what code style should be followed first consult this doc, then PEP-8 and if all fails use your best judgement or ask for help.

Indentation

Use 4 spaces per indentation level, This can be setup in vi with: set tabstop=4 set shiftwidth=4 set expandtab

Continuation lines should be wrapper like this:

foo = long_function_name(var_one, var_two,
                         var_three, var_four)

or this:

def long_function_name(var_one,
            var_two, var_three,
            var_four):
    print(var_one)

They should NOT be wrapper like this:

foo = long_function_name(var_one, var_two,
        var_three, var_four)

and NOT like this:

# See how it creates confusion with what is inside the function?
def long_function_name(var_one,
    var_two, var_three,
    var_four):
    print(var_one)

Tabs or Spaces?

Everytime you insert a \t into any piece of code a kitten dies, painfully.

Only spaces. Please.

(code should be run with python -tt)

Maximum Line Length

Maximum of 79 characters. 72 characters for long blocks of text is recommended.

You can use this piece of code inside of your .vimrc to make it happen automatically:

set foldmethod=indent
set foldlevel=99
set textwidth=79

Blank Lines

Separate top-level function and class definitions with two blank lines.

Method definitions inside of class are separated by a single blank line.

Encoding

Always use UTF-8 encoding. This can be specified by add the encoding cookie to the beginning of your python files:

# -*- coding: UTF-8

All identifiers should be ASCII-only. All doc strings and comments should also only be in ASCII. Non ASCII characters are allowed when they are related to testing non-ASCII features or for the names of authors.

Imports

Import should be one per line as so:

import os
import sys
from subprocess import Popen, PIPE

Imports are always at the top of the file just after any module comments and docstrings, berfore module globals and constants.

Imports should be grouped in the following order:

1. standard library imports
2. related third party imports
3. local application/library specific imports

You should put a blank line between each group of imports.

Comments

Comments should always be up to date with the code. Don't have comments that contraddict with the code.

Comments should always be written in English.

Blocks comments are indented to the same level of the code that they refer to. They start with # and are followed by a single space.

Use inline comments sparingly. # Gotcha?

Documentation strings

Write docstrings for all public modules, functions, classes and methods. Even better if you write them also for non-public methods.

Place docstrings under the def.

For a better overview on how to write docstrings consult: PEP-257

Naming convention

Avoid using 'l' (lowercase letter el), 'O' (uppercase letter oh) or I (uppercase letter eye) as single character variable names.

Module names should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

Class names should follow the CapWords convention. Note: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus HTTPServerError is better than HttpServerError.

Function names should be all lowercase with words separated by underscores to improve readability. The same goes for Global Variable names.

Method names should be all lowercase. Non-public methods should start with an underscore. The same applies to instance variables.

Exception names should follow the class names convention as exceptions should be classes, like the extended Twisted classess (they use Method name InCamelCase)