Coding Style Guide

Skip to end of metadata
Go to start of metadata

General

  • 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.
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.