Coding standards and best practices

From Post-Apocalyptic RPG wiki

Jump to: navigation, search

Established workflow.png This article covers an established workflow.

Established workflows have been discussed among and agreed upon by the development department(s). They should serve as documentation how these workflows are successfully utilized in the project.

These are the agreed upon coding standards that apply when writing code for the project.

Contents

Code Style Guidelines

PARPG follows the PEP8 code style guide, with the following exception:

  • All method and function names must be mixedCase;

We also adhere to the following, additional, guidelines:

  • Indent any if conditional statements that don't fit on one line three (3) additional spaces on the next line. Use a backslash "\" to break the newlines, not parentheses "(...)".
# Correct
if condition1 and \
   condition2 and \
   condition3:
    do_someting()
# Incorrect
if (condition1 and
    condition2 and
    condition3):
    do_something()
  • For multiline docstrings, the """ symbols should be on their own line and all other lines should be indented to the same level as the """ symbols.
# Correct
def func():
    """
    This is a multiline function docstring.
 
    Here is some additional information about
    the function.
    """
# Incorrect
def func():
    """This is a multiline function docstring.
 
    Here is some additional information about
    the function.
    """
# Incorrect
def func():
    """This is a multiline function docstring.
 
       Here is some additional information about
       the function.
    """

Pylint

There is a pylintrc file in the game directory that contains the standards described here for use by pylint.

Code Documentation

  • Every public function, method, class and module should have a docstring;
  • Docstrings should start with a brief, one-sentence description of the object it documents;
    • For methods and functions this description should start with a simple present-tense verb that describes the action that the method or function accomplishes, e.g. "perform x" instead of "this function performs x" or "calling this function will perform x";
  • All function/method parameters and return values must be documented using Epytext markup (see below);
  • Class and instance variables should be documented in the class docstring, not the constructor docstring;

Epydoc

The PARPG project uses Epydoc to automatically generate code documentation from docstrings using a special markup language called Epytext. The current documentation can be found at http://parpg.boxbox.org/ and help with epydoc formats can be found at http://epydoc.sourceforge.net/manual-epytext.html;

A (somewhat silly) example of Epytext markup in a function docstring:

def castSpell(spell, mana):
    """
    Cast a spell.
 
    @type spell: str
    @param spell: Name of the spell to cast.
    @type mana: int
    @param mana: Amount of mana used when the spell is cast.
 
    @rtype: int
    @return: Amount of mana left.
    """

Here each function parameter is documented with two tags: a @type tag that specifies the expected type of the parameter, and a @param tag which is a concise description of the parameter and how it is used. The function's return value is documented using the @rtype tag which specifies the type of the returned value, and @return tag which is a concise description of the return value.

Other keywords are supported as well, and a complete list can be found at http://epydoc.sourceforge.net/manual-fields.html.

General guidelines for using Epytext markup in your docstrings:

  • @type tags should specify the most general Python type that describes the parameter, which may be a protocol/Abstract Base Class (a.k.a. ABC). For example, for a dictionary-like object is probably better for the @type tag should specify the collections.MutableMapping ABC rather than dict;
    • When the type of a parameter or variable is a documented class defined within PARPG it should be linked to its documentation via the L{displayName<actualName>} markup;
  • If a function does not explicitly return a value, then simply enter @return: None;

Unit Testing

Unit testing is strongly encouraged wherever possible. For unit testing guidelines see Unit testing standards and best practices.

Personal tools