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 spacesReturns:
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.