This is the OpenBlox coding standard, which closely follows Python PEP 8 (http://www.python.org/dev/peps/pep-0008/). If you have any questions concerning this document, send a message to OpenBlox (http://openblox.sf.net/users/openblox).
Note
If you haven’t already, read the OpenBlox CLA (Contributor License Agreement).
Note
The build-helper convert_newlines.py will automatically convert all your newlines for you. To run it on Windows (assuming you’re in the build-helpers directory), type:
python convert_newlines.py
# If Python isn't contained in one of the directories specified in your
# %PATH% environment variable (which is the case when you install Python)
# use this command, instead:
# C:\Python26\python convert_newlines.py
To run it on *nix (i.e, Linux, Mac OSX, *BSD) (again, assuming you’re in the build-helpers directory):
./convert_newlines.py
# If the env program isn't installed inside /usr/bin on your system,
# use this command instead:
# python convert_newlines.py
Examples:
# Set a
a = 1
# complicated_method is complex,
# so we need several lines to explain it, and we
# end this explanation with a period.
complicated_method(f, o, o, b, a, r, s, p, a, m, e, g, g, s)
Every module, function, and public class method should have a docstring.
Docstrings should be written with normal text.
A docstring’s basic format is this:
"""Quick one-liner summary (no ending period)
In-depth explanation of whatever this docstring belongs to.
This includes explanation of parameters (and their expected type), return value,
and possibly raised exceptions (where applicable).
As you can see, each sentence has an ending period.
"""
If the docstring belongs to a function, method, or class, then it should have a small doctest suite (normally 2-4 complete tests [i.e, 2-4 tests of that docstring’s owner] are fine), to provided regression testing, and to provide a form of runnable documentation.
A unit test is like the doctests inside a docstring (indeed, they look basically identical), but each unit test is in a seperate file, contained in the test-suite directory.
Example:
This is an example unit test comment. It is ignored by the test runner.
The next three lines are run by the test runner, as they both start with
">>> ".
>>> import obengine.cfg
>>> cfg = obengine.cfg.Config()
>>> cfg is cfg
True
See? Just like a normal doctest.
This line is also ignored.
Examples:
foo_bar = 0
eggs_n_spam = [ 0, 1, 2, 3, 4, 5]
#method declaration here
Examples:
# Single loop with single logical line
for x in range(0, 5):
print x
# Single loop with multiple logical lines
for x in range(1, 11):
x += 5
print x
# Nested loops with single logical line
for x in range(0, 5):
for y in range(0, 5):
print 'Nested loops with only one logical line should look like this!'
# Nested loops with multiple logical lines
for x in range(0, 5):
for y in range(0, 5):
print 'This is inside a nested loop with multiple'
print 'logical lines, so there is a blank line'
print 'between the last loop declaration, and'
print 'the first non-loop line'
Example:
def do_x(a, b, c):
"""Does x
Prints a, the first element of b, and the second element of c,
all on a single line.
"""
print a, b[0], c[1]
Example:
class ClassA(object):
"""
ClassA is for XYZ.
Volatile - ClassA's interface might change in the future!
"""
def __init__(self):
"""Initalizes ClassA
No arguments are given.
"""
print 'Initalized an instance of ClassA!'
def foo(self, a):
"""Prints a
Arguments:
* a - the object to print
Returns: None
"""
self._bar(a)
def _bar(self, a):
print a
Modules have this header, at their beginning:
#
# <module description>
# See <TODO: No Sphinx docs yet - add some> for the primary source of documentation
# for this module.
#
#
# Copyright (C) <inital year released>-<last modified year> The OpenBlox Project
#
# This file is part of The OpenBlox Game Engine.
#
# The OpenBlox Game Engine is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# The OpenBlox Game Engine is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with The OpenBlox Game Engine. If not, see <http://www.gnu.org/licenses/>.
#
Note
If your module has only been included (so far) in 1 version of OpenBlox, you can use this copyright line, instead:
# Copyright (C) <inital year released> The OpenBlox Project
Also, if your module hasn’t been modified in every year it’s been included with OpenBlox, use this copyright line:
# Copyright (C) <inital year released>, <modified years, seperated by a comma> The OpenBlox Project
For example, if your module was released in 2009, and was modified in 2010 and 2011, you should use:
# Copyright (C) 2009-2011 The OpenBlox Project
On the other hand, if your module was released in 2008, and modified in 2009 and 2011, you should use:
# Copyright (C) 2008, 2009, 2011 The OpenBlox Project
Note
If you are writing a Python package, then source files located in your package (save for __init__.py) need not have the Sphinx documentation link. This doesn’t apply to the obengine package, however.