deb-zaqar/HACKING.rst
venkatamahesh 62ebf7b222 Fix few typos in headings
1.) Corrected headings according to rules of migrations by
placing "=======" on headings in the files
2.) Some headings have extra "====", they are removed
3.) Launchpad url have '~' which makes error: page not found
,so it is removed

Change-Id: I99581025d579f18da9ebe57267fb002cbcba28dd
2015-09-19 16:37:56 +05:30

136 lines
4.1 KiB
ReStructuredText

========================
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.transport.wsgi as wsgi
**CORRECT** ::
from zaqar.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__)