From 90774202e2ac0e5394fd459f04cfd590062f7d25 Mon Sep 17 00:00:00 2001
From: kgriffs <kurt.griffiths@rackspace.com>
Date: Thu, 21 Mar 2013 10:32:16 -0400
Subject: [PATCH] style(HACKING): Add notes about whitespace, naming, and
 wrapping

This patch is all about optimizing our coding style around readibility:

* Developers spend more time reading code than writing it.
* Newcomers have little (or no) context to draw upon when trying to understand the intent of the original author.
* Code is easier to reason about when it is self-documenting.

Change-Id: If7428195aa31104f194cb240faf5c6946d068e8d
---
 HACKING.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 46 insertions(+), 7 deletions(-)

diff --git a/HACKING.rst b/HACKING.rst
index 3425729b6..d897129e2 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -8,11 +8,50 @@ Marconi Style Commandments
 
 General
 -------
-- Put two newlines between top-level code (funcs, classes, etc)
-- Put one newline between methods in classes and anywhere else
-- Do not write "except:", use "except Exception:" at the very least
-- Include your name with TODOs as in "#TODO(termie)"
-- Do not name anything the same name as a built-in or reserved word
+- Optimize for readability; whitespace is your friend.
+- Put two newlines between top-level code (funcs, classes, etc.)
+- Put one newline between methods in classes and anywhere else.
+- Use blank lines to group related logic.
+- Do not write "except:", use "except Exception:" at the very least.
+- Include your name with TODOs as in "#TODO(termie)".
+- All classes must inherit from "object" (explicitly).
+
+Identifiers
+-----------
+- Do not give anything the same name as a built-in or reserved word.
+- Don't use single characters in identifiers except in trivial loop variables and mathematical algorithms.
+- Avoid abbreviations, especially if they are ambiguous or their meaning would not be immediately clear to the casual reader or newcomer.
+
+Wrapping
+--------
+Wrap long lines by using Python's implied line continuation inside
+parentheses, brackets and braces. Make sure to indent the continued
+line appropriately. The preferred place to break around a binary
+operator is after the operator, not before it.
+
+Example::
+
+  class Rectangle(Blob):
+
+      def __init__(self, width, height,
+                   color='black', emphasis=None, highlight=0):
+
+          # More indentation included to distinguish this from the rest.
+          if (width == 0 and height == 0 and
+                  color == 'red' and emphasis == 'strong' or
+                  highlight > 100):
+              raise ValueError('sorry, you lose')
+
+          if width == 0 and height == 0 and (color == 'red' or
+                                             emphasis is None):
+              raise ValueError("I don't think so -- values are %s, %s" %
+                               (width, height))
+
+          msg = ('this is a very long string that goes on and on and on and'
+                 'on and on and on...')
+
+          super(Rectangle, self).__init__(width, height,
+                                          color, emphasis, highlight)
 
 
 Imports
@@ -54,11 +93,11 @@ More Import Examples
 
 **INCORRECT** ::
 
-    import marconi.transport.wsgi as wsgi
+  import marconi.transport.wsgi as wsgi
 
 **CORRECT** ::
 
-    from marconi.transport import wsgi
+  from marconi.transport import wsgi
 
 Docstrings
 ----------