Coding Style Guide

General

• Strictly follow http://www.python.org/dev/peps/pep-0008/ if not specified otherwise.

• Consistency at first! Look at the code around and try to produce something similar.

Note We have a very nice SIO2 Coding Style Cheat Sheet for you to print!

Miscellaneous notes

• Do not use accessor methods (set_something, get_something). Use @property instead.

• Docstring: single-paragraph docstrings look like this:
  Unknown macro: {code}

  def function(param):
  """Returns a value, which is a return value of this function, which
  returns a value."""

• Docstring: multiple-paragraph look like this:
  Unknown macro: {code}

  def list_to_string(list_, delimiter=' '):
  """Short summary here. If wraps, the next line starts
  aligned to the text in the first line. Write something
  more than "Constructor.", but not longer than 3 lines.

  Here is a more elaborate description of what the
  function does, what arguments it accepts and what
  returns. Alternatively, a list may be more appropriate
  (example below).

  Do not forget about explicitly specifying acceptable types
  of arguments and the type of return value.

  Also, remember to use reStructuredText.

  Args:
  ``list``: list to convert to string
  ``delimiter``: string to use as a delimiter; if the description
  wraps, following lines are indented by 2 more spaces

  Returns:
  a string containing concatenated string representations of
  element of ``list``, delimited by the specified ``delimiter``

  Use single backquotes for quoting elements, which may be linked
  in the documentation (classes, methods, etc.), but use double
  backquotes for argument names, constants, ``None`` etc.

  As you can see, internal tab size is 2 characters. Weird, isn't
  it?

  And, by the way, if you think it's stupid, try to change it,
  but do it in a professional way. Just complaining is never
  professional. Look around the code if the convention
  is followed, talk with the others if the proposed change
  is acceptable and be ready to coordinate updating the
  code to adhere to a new convention, make sure scripts
  for it are prepared, and be ready to update the documentation.
  And... be efficient, don't spend too much time on it,
  estimate if it's worth the effort at all.
  """

• Docstring: class
  Unknown macro: {code}

  class MyClass(object):
  """Short summary here. Same as for functions/methods.

  Then a more elaborate description of what the
  class does and how to use it. Examples go here, too.

  If instances of this class have any public attributes, they
  must be documented here, like this:

  Attributes:
  `name`: human-readable string, used in generated
  log messages
  `id`: (read-only) unique identifier, integer
  """

  PublicClassField = 12
  """Description of what is this for. One line is ok, but
  sometimes more info is needed. If the description is
  long, write a summary first, just like for functions."""

  databaseMappedField = String(255)
  """Same as for public class fields."""

• Text which may be translated in the future must be in double quotes. Of course, use _("some text") if it makes sense. Some modules do not support it yet — leave double quotes in this case.

• Do not specify encoding of Python file if not needed. If needed, always use utf8.

• Do not forget to escape content which may contain special characters in Jinja templates.