CONTRIBUTING.md

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