code_style: more formatting
1 files changed, 57 insertions, 34 deletions
diff --git a/docs/code_style.rst b/docs/code_style.rst
index 38d52abd47..a7a71686ba 100644
--- a/docs/code_style.rst
+++ b/docs/code_style.rst
@@ -1,49 +1,72 @@
- Everything should comply with PEP8. Code should pass
``pep8 --max-line-length=100`` without any warnings.
-- NEVER tabs. 4 spaces to indent.
-- Max line width: 79 chars (with flexibility to overflow by a "few chars" if
+
+- **Indenting**:
+
+ - NEVER tabs. 4 spaces to indent.
+
+ - follow PEP8; either hanging indent or multiline-visual indent depending
+ on the size and shape of the arguments and what makes more sense to the
+ author. In other words, both this::
+
+ print("I am a fish %s" % "moo")
+
+ and this::
+
+ print("I am a fish %s" %
+ "moo")
+
+ and this::
+
+ print(
+ "I am a fish %s" %
+ "moo",
+ )
+
+ ...are valid, although given each one takes up 2x more vertical space than
+ the previous, it's up to the author's discretion as to which layout makes
+ most sense for their function invocation. (e.g. if they want to add
+ comments per-argument, or put expressions in the arguments, or group
+ related arguments together, or want to deliberately extend or preserve
+ vertical/horizontal space)
+
+- **Line length**:
+
+ Max line length is 79 chars (with flexibility to overflow by a "few chars" if
the overflowing content is not semantically significant and avoids an
explosion of vertical whitespace).
-- Use camel case for class and type names
-- Use underscores for functions and variables.
-- Use double quotes.
-- Use parentheses instead of '\\' for line continuation where ever possible
- (which is pretty much everywhere)
-- There should be max a single new line between:
+
+ Use parentheses instead of ``\`` for line continuation where ever possible
+ (which is pretty much everywhere).
+
+- **Naming**:
+
+ - Use camel case for class and type names
+ - Use underscores for functions and variables.
+
+- Use double quotes ``"foo"`` rather than single quotes ``'foo'``.
+
+- **Blank lines**:
+
+ - There should be max a single new line between:
+
- statements
- functions in a class
-- There should be two new lines between:
- - definitions in a module (e.g., between different classes)
-- There should be spaces where spaces should be and not where there shouldn't be:
- - a single space after a comma
- - a single space before and after for '=' when used as assignment
- - no spaces before and after for '=' for default values and keyword arguments.
-- Indenting must follow PEP8; either hanging indent or multiline-visual indent
- depending on the size and shape of the arguments and what makes more sense to
- the author. In other words, both this::
- print("I am a fish %s" % "moo")
+ - There should be two new lines between:
- and this::
-
- print("I am a fish %s" %
- "moo")
+ - definitions in a module (e.g., between different classes)
- and this::
+- **Whitespace**:
- print(
- "I am a fish %s" %
- "moo"
- )
+ There should be spaces where spaces should be and not where there shouldn't
+ be:
- ...are valid, although given each one takes up 2x more vertical space than
- the previous, it's up to the author's discretion as to which layout makes most
- sense for their function invocation. (e.g. if they want to add comments
- per-argument, or put expressions in the arguments, or group related arguments
- together, or want to deliberately extend or preserve vertical/horizontal
- space)
+ - a single space after a comma
+ - a single space before and after for '=' when used as assignment
+ - no spaces before and after for '=' for default values and keyword arguments.
-- Comments should follow the `google code style
+- **Comments**: should follow the `google code style
<http://google.github.io/styleguide/pyguide.html?showone=Comments#Comments>`_.
This is so that we can generate documentation with `sphinx
<http://sphinxcontrib-napoleon.readthedocs.org/en/latest/>`_. See the
|
