diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b068f0..0e0b107 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,13 +6,22 @@ Before submitting a pull request, please ensure you have added/updated the appro #### 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). * When catching exceptions, name the variable `ex`. * Use whitespace to separate logical blocks of code and to improve readability. * No single-character variable names except for trivial indexes when looping, or in mathematical expressions implementing well-known formulas. * Heavily document code that is especially complex and/or clever. +* When in doubt, optimize for readability. [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