Zaqar Style Commandments
========================

- Step 1: Read the OpenStack Style Commandments
  http://docs.openstack.org/developer/hacking/
- Step 2: Read on for Zaqar specific commandments

General
-------
- Optimize for readability; whitespace is your friend.
- Use blank lines to group related logic.
- All classes must inherit from ``object`` (explicitly).
- Use single-quotes for strings unless the string contains a
  single-quote.
- Use the double-quote character for blockquotes (``"""``, not ``'''``)
- USE_ALL_CAPS_FOR_GLOBAL_CONSTANTS

Comments
--------
- In general use comments as "memory pegs" for those coming after you up
  the trail.
- Guide the reader though long functions with a comments introducing
  different sections of the code.
- Choose clean, descriptive names for functions and variables to make
  them self-documenting.
- Add ``# NOTE(termie): blah blah...`` comments to clarify your intent, or
  to explain a tricky algorithm, when it isn't obvious from just reading
  the code.


Identifiers
-----------
- 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 {0}, {1}".format(
                               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
-------
- Classes and functions may be hoisted into a package namespace, via __init__ files, with some discretion.

More Import Examples
--------------------

**INCORRECT** ::

  import zaqar.queues.transport.wsgi as wsgi

**CORRECT** ::

  from zaqar.queues.transport import wsgi

Docstrings
----------

Docstrings are required for all functions and methods.

Docstrings should ONLY use triple-double-quotes (``"""``)

Single-line docstrings should NEVER have extraneous whitespace
between enclosing triple-double-quotes.

**INCORRECT** ::

  """ There is some whitespace between the enclosing quotes :( """

**CORRECT** ::

  """There is no whitespace between the enclosing quotes :)"""

Docstrings should document default values for named arguments
if they're not None

Docstrings that span more than one line should look like this:

Example::

  """Single-line summary, right after the opening triple-double-quote.

  If you are going to describe parameters and return values, use Sphinx; the
  appropriate syntax is as follows.

  :param foo: the foo parameter
  :param bar: (Default True) the bar parameter
  :param foo_long_bar: the foo parameter description is very
    long so we have to split it in multiple lines in order to
    keey things ordered
  :returns: return_type -- description of the return value
  :returns: description of the return value
  :raises: AttributeError, KeyError
  """

**DO NOT** leave an extra newline before the closing triple-double-quote.

Creating Unit Tests
-------------------
NOTE: 100% coverage is required

Logging
-------
Use __name__ as the name of your logger and name your module-level logger
objects 'LOG'::

    LOG = logging.getLogger(__name__)