PyOGP Coding Guidelines

   http://www.python.org/dev/peps/pep-0008/
   http://www.python.org/dev/peps/pep-0257/

https://wiki.lindenlab.com/wiki/Coding_Standard#Python

unit tests: (https://wiki.lindenlab.com/wiki/Automatic_Unit_Testing#Using_minimock)

Source Files

Begin all Python source code files with this header:

"""
@file filename
@brief brief description
Contributors: http://svn.secondlife.com/svn/linden/projects/2008/pyogp/CONTRIBUTORS.txt 

$LicenseInfo:firstyear=2008&license=apachev2$

Copyright (c) 2009, Linden Research, Inc.

Licensed under the Apache License, Version 2.0 (the "License").
You may obtain a copy of the License at:
    http://svn.secondlife.com/svn/linden/projects/2008/pyogp/LICENSE.txt
$/LicenseInfo$
"""

Whitespace

4 spaces is our standard indentation. Please do not mix in tabs. Really.

emacs

Put this in your ~/.emacs to get the desired behavior (note that this also turns on colored fonts, which you probably wanted anyway):

(defun ll-python-mode-hook()
  (font-lock-mode 1)
  (font-lock-fontify-buffer)
  (set-variable 'indent-tabs-mode nil)
  (set-variable 'py-indent-offset 4)
  (message "ll coding style function executed"))
(add-hook 'python-mode-hook 'll-python-mode-hook)

(insert instructions on using python-mode if it's not with your default emacs install)

To convert tabs to spaces in Emacs:

• Make sure your tab width is 4
  • In .emacs (set-variable 'tab-width 4) (optionally inside your ll-python-mode-hook())
  • Immediately: M-x set-variable[ret] tab-width[ret] 4[ret]
• Set mark at start of file: M-< ^space
• Jump to end of file: M->
• Convert tabs to spaces within marked range: M-x untabify

vi

To use spaces instead of tabs in vi put this in ~/.vimrc:

set tabstop=4
set shiftwidth=4
# When reading a file or creating a new file, uses spaces not tabs
autocmd BufRead,BufNewFile *.py set expandtab

Another option for tabs/spaces:

# automatically expand tab keypresses into the appropriate number of spaces
set expandtab

Imports

• Include only one module per line
• Order your imports alphabetically (this gets a little vague with "from x in y" imports TODO: invent a rule that makes sense)
• Try not to pollute the module's namespace by importing individual functions and classes from other modules.

bad:

from os.path import join, dirname, realpath
from pyogp.lib.base import agent, region

good:

import os.path
import socket
import urllib2
from pyogp.lib.base.agent import Agent
from pyogp.lib.base.region import Region

Docstrings

The standard here is pulled from http://www.python.org/dev/peps/pep-0257/, which is our guideline.

Mechanics:

1. Use triple double quotes for docstring: """this is a docstring""".
2. The text should describe the functionality of the function or method, and should only describe the parameters and return values when it is not clear.
3. Use one line docstrings when possible.
4. When using a multiline docstring, the first line should be the descriptive, followed by a blank line, followed by details in subsequent lines.