openstack/deb-python-falcon
Code Issues Proposed changes

doc(CONTRIBUTING): Add notes about Napolean and comment prefixes

Browse Source
This commit is contained in:
kgriffs
2014-04-07 16:56:21 -05:00
parent 5b372a45a8
commit 11eb17e284
1 changed files with 11 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
CONTRIBUTING.md
View File

@@ -6,13 +6,22 @@ Before submitting a pull request, please ensure you have added/updated the appro
#### Additional style rules #### #### Additional style rules ####
* Comments follow [Google's style guide][goog-style-comments]. * Docstrings are required for classes, attributes, methods, and functions.
* Docstrings are [napolean-flavored][docstrings] so they look good from both
the CLI and in RTD.
* Format non-trivial comments using your GitHub nick and one of these prefixes:
* TODO(riker): Damage report!
* NOTE(riker): Well, that's certainly good to know.
* PERF(riker): Travel time to the nearest starbase?
* APPSEC(riker): In all trust, there is the possibility for betrayal.
* Commit messages should be formatted using [AngularJS conventions][ajs] (one-liners are OK for now but body and footer may be required as the project matures). * Commit messages should be formatted using [AngularJS conventions][ajs] (one-liners are OK for now but body and footer may be required as the project matures).
* When catching exceptions, name the variable `ex`. * When catching exceptions, name the variable `ex`.
* Use whitespace to separate logical blocks of code and to improve readability. * Use whitespace to separate logical blocks of code and to improve readability.
* No single-character variable names except for trivial indexes when looping, * No single-character variable names except for trivial indexes when looping,
or in mathematical expressions implementing well-known formulas. or in mathematical expressions implementing well-known formulas.
* Heavily document code that is especially complex and/or clever. * Heavily document code that is especially complex and/or clever.
* When in doubt, optimize for readability.
[ajs]: http://goo.gl/QpbS7 [ajs]: http://goo.gl/QpbS7
[goog-style-comments]: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments [docstrings]: http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html#example-google-style-python-docstrings
[goog-style]: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments