summary refs log tree commit diff
path: root/docs/code_style.rst
diff options
context:
space:
mode:
authorMark Haines <mark.haines@matrix.org>2014-12-10 16:55:06 +0000
committerMark Haines <mark.haines@matrix.org>2014-12-10 16:55:06 +0000
commit4f37c0ea9dd99b76258d07059e5f2dc6549f3f95 (patch)
tree3130a9b275d0f77c04118d54334ca3d4a9b7d71d /docs/code_style.rst
parentupdate media repository implementation docs (diff)
parentoops (diff)
downloadsynapse-4f37c0ea9dd99b76258d07059e5f2dc6549f3f95.tar.xz
Merge branch 'develop' into media_repository
Diffstat (limited to 'docs/code_style.rst')
-rw-r--r--docs/code_style.rst37
1 files changed, 34 insertions, 3 deletions
diff --git a/docs/code_style.rst b/docs/code_style.rst
index d7e2d5e69e..dc40a7ab7b 100644
--- a/docs/code_style.rst
+++ b/docs/code_style.rst
@@ -1,10 +1,14 @@
 Basically, PEP8
 
-- Max line width: 80 chars.
+- NEVER tabs. 4 spaces to indent.
+- Max line width: 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)
+- Use parentheses instead of '\\' for line continuation where ever possible
+  (which is pretty much everywhere)
 - There should be max a single new line between:
     - statements
     - functions in a class
@@ -14,5 +18,32 @@ Basically, PEP8
     - 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::
 
-Comments should follow the google code style. This is so that we can generate documentation with sphinx (http://sphinxcontrib-napoleon.readthedocs.org/en/latest/) 
+    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)
+
+Comments should follow the google code style. This is so that we can generate
+documentation with sphinx (http://sphinxcontrib-napoleon.readthedocs.org/en/latest/) 
+
+Code should pass pep8 --max-line-length=100 without any warnings.