summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorMaryam Tahhan <maryam.tahhan@intel.com>2015-06-08 15:03:08 +0000
committerGerrit Code Review <gerrit@172.30.200.206>2015-06-08 15:03:08 +0000
commitf3f1ff9b08efa4a18bdcd2284d0a5f3b6ee526e0 (patch)
treea736bab8be95381d2277626c8df2f88ccce714d0 /CONTRIBUTING.md
parent1612a95c88e6ccff6f9b158f9b106e410b1d7324 (diff)
parent8d6777df09c3dc441013a31f21cc50ab3b0f42a3 (diff)
Merge "framework: Add reworked framework to repo"
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md65
1 files changed, 65 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..91dc6d25
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,65 @@
+# General Coding Style
+
+## Code
+
+Abide by [PEP-8] for general code. Some particular points to note:
+
+* Wrap code at 79 characters.
+* Use only spaces - no tabs.
+* Use implicit string concatenation where possible. Don't use the escape
+ character unless absolutely necessary.
+* Be liberal in your use of whitespace to group related statements together.
+ However, don't leave a space after the docstring and the first statement.
+* Use single quotes for all string literals.
+
+## Documentation
+
+Follow [PEP-257] and the [Sphinx guidelines] for documentation. In particular:
+
+* Wrap docstrings at 72 characters.
+* Use double-quotes for all docstrings.
+* Write all inline comments in lower-case, except where using a name/initialism.
+* Document **all** library functions/classes completely. Tests, however, only need a test case docstring.
+
+To summarise the docstring conventions:
+
+```python
+def my_function(athing, stuff=5):
+ """
+ Summary line here in imperative tense.
+
+ Longer description here...
+
+ :param athing: Details about this paramter here
+ :param stuff: Ditto
+
+ :returns: None
+ """
+ pass # code here...
+```
+
+### Validation
+
+All code should be checked with the PyLint linter and PEP8 style guide checker.
+Pylint can be run like so:
+
+```bash
+pylint <file or directory>
+```
+
+Most PyLint errors should be resolved. You will need to do this manually.
+However, there are cases where they may not make sense (e.g. you **need** to
+pass `N` parameters to a function). In this case, disable the relevant
+case using an inline `disable` like so:
+
+```python
+# pylint: disable=[code]
+```
+
+On the other hand, all PEP8 errors should be resolved.
+
+---
+
+[PEP-8]: http://legacy.python.org/dev/peps/pep-0008/
+[PEP-257]: http://legacy.python.org/dev/peps/pep-0257/
+[Sphinx guidelines]: https://pythonhosted.org/an_example_pypi_project/sphinx.html