Skip to content. | Skip to navigation

Personal tools
Log in
You are here: Home Software James's Coding Style

James's Coding Style

James's adaptation of the galaktia coding style guidelines.


Documentation Conventions

Documentation will be based upon the following Python packages:

I will use reStructuredText as markup language for documentation.

For conventions on documentation fields, refer to the Epydoc Fields manual.

Note that any Epydoc field starting with @ can be translated to reStructuredText markup as in the following example:

  • Epydoc: @cmd foo: bar baz
  • reStructuredText: :cmd foo: bar baz


reStructuredText Parameter List Quick Reference

data : sequence
observations as a 1-d sequence such as
a `numpy.ndarray` of shape ``(1,)``
N_0 : int
specifies the number of initial bins to try

parts : int
specifies the number of partitions for cost function smoothing


Quick Reference for Documentation Body

Reference TypeStyleExample
Parameter inline literal
The ``color`` parameter specifies...
Class interpreted text
that instances of `Helix` will...
interpreted text with
tailing parens
An `Axis()` of a `Helix()` is...
Function (link)
interpreted text with
tailing underscore
because `twist`_ is different from `writhe`_...
Function (no link) interpreted text with
tailing parens
because `twist()` is different from `writhe()`...
Built-in inline literal
The method will return ``False``...
Object Attribute emphasis
while the `Helix()` has integer *pitch*
Module interpreted text
...if using the `array` module...
Literal inline literal
...but not if `input` is ``42``

Module Level

inline literal
...which would be less than ``MAXTOT``,
...or less than *total*.
Inline Snippet inline literal
``[10, 0, 0]`` : translate 10 along X


Full Example

#!/usr/bin/env python

# -*- coding: utf-8 -*-

This module **foobar** serves as an *example* of documentation style for
**Python** using Docutils_' reStructuredText_ as markup language.

.. _Docutils:
.. _reStructuredText:

..  This is a comment, the following line too.
    The following fields define some module metadata.

:date: '2009-08-07'
    - Walter
    - Walterina

= '0.1'
= 'GNU General Public License 3'
= 'restructuredtext en'

# Recommended order of imports is (alphabetically sorted in each group):
# - standard library
# - third party libraries
# - internal modules
# Also:
# - "import a.b" is preferred over "from a import b"
# - "from a import b" is preferred over "from a import *"

import logging
import os
import sys

import simplejson

import galaktia.client
import galaktia.server

# Constants are written ALL_IN_CAPS
# Variables are written in lowercase_with_underscore
# Internals are preceded with an underscore

= 60
= re.compile(r'\w+')
= datetime.utcnow()
= {}

class Walter(object):
    Model for a Walter sprite in a virtual world.

    Walters can do amazing stuff such as walking and pushing boxes.

= 0 # a class variable
""":cvar: Some class variable."""

= None # an instance variable
""":ivar: Some instance variable."""

def __init__(self, avatar, lives=0, **kwargs):
        `Walter` initializer.

        Initializing a `Walter` is extremely funny. You should try it!

          avatar : unicode
            An identifier for `Walter`'s appearance.
          lives : int
            Number of lives `Walter` initially has.

          position : tuple(int, int)
            `Walter`'s position in a 2-tuple.

          - `ValueError`: Raised when `lives` is less than ``0``.

          You should write class names between backtics (`````), as in
          ```Walter``` to get links to that object as in `Walter`.

self._avatar = avatar
if lives < 0:
raise ValueError(lives)
self._lives = lives
self._position = kwargs.get('position', (0, 0))

def move(self, direction='up'):
        Makes `Walter` move one step towars given ``direction``.

        :return: ``True`` if `Walter` could move. ``False`` otherwise.

          direction : str
            Determines the direction where to move.

            Posible values are:

              - ``'up'``
              - ``'left'``
              - ``'down'``
              - ``'right'``

, dy = self._can_move(direction)
if None in (dx, dy):
return False
self._position = (self._position[0] + dx, self._position[1] + dy)
return True

# the only non-empty lines before the module docstring may be:
#   - shebang (#!/usr/bin/env python)
#   - file encoding line (# -*- coding: utf-8 -*-)
#   - __future__ imports