CONTRIBUTING.md

   1 # General Coding Style
   2
   3 ## Code
   4
   5 Abide by [PEP-8] for general code. Some particular points to note:
   6
   7 * Wrap code at 79 characters.
   8 * Use only spaces - no tabs.
   9 * Use implicit string concatenation where possible. Don't use the escape
  10   character unless absolutely necessary.
  11 * Be liberal in your use of whitespace to group related statements together.
  12   However, don't leave a space after the docstring and the first statement.
  13 * Use single quotes for all string literals.
  14
  15 ## Documentation
  16
  17 Follow [PEP-257] and the [Sphinx guidelines] for documentation. In particular:
  18
  19 * Wrap docstrings at 72 characters.
  20 * Use double-quotes for all docstrings.
  21 * Write all inline comments in lower-case, except where using a name/initialism.
  22 * Document **all** library functions/classes completely. Tests, however, only need a test case docstring.
  23
  24 To summarise the docstring conventions:
  25
  26 ```python
  27 def my_function(athing, stuff=5):
  28    """
  29    Summary line here in imperative tense.
  30
  31    Longer description here...
  32
  33    :param athing: Details about this paramter here
  34    :param stuff: Ditto
  35
  36    :returns: None
  37    """
  38    pass  # code here...
  39 ```
  40
  41 ### Validation
  42
  43 All code should be checked with the PyLint linter and PEP8 style guide checker.
  44 Pylint can be run like so:
  45
  46 ```bash
  47 pylint <file or directory>
  48 ```
  49
  50 Most PyLint errors should be resolved. You will need to do this manually.
  51 However, there are cases where they may not make sense (e.g. you **need** to
  52 pass `N` parameters to a function). In this case, disable the relevant
  53 case using an inline `disable` like so:
  54
  55 ```python
  56 # pylint: disable=[code]
  57 ```
  58
  59 On the other hand, all PEP8 errors should be resolved.
  60
  61 ---
  62
  63 [PEP-8]: http://legacy.python.org/dev/peps/pep-0008/
  64 [PEP-257]: http://legacy.python.org/dev/peps/pep-0257/
  65 [Sphinx guidelines]: https://pythonhosted.org/an_example_pypi_project/sphinx.html