Designate/Development/StyleGuide

# -*- coding: utf-8 -*-
# Copyright <year> <company>
#
# Author: <name> <email addr>
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.

"""
    <package.module>
    ~~~~~~~~~~~~~~
    <Describe what the module should do, especially interactions with other components>
    Specs: <Link to the spec document>
"""

Docstrings

Use the Sphinx markup. Here is an example:

class MyClass(object):
    """<description>
    mention a function :func:`foo` or a class :class:`Bar`
    """

    def function(self, foo):
        """<describe what the function does>
        :param foo: <description>
        :type foo: <type>
        :returns: <describe the returned value>
        :rtype: <returned type>
        :raises: <list raised exceptions>

        :Example:

        >>> a = b - c
        >>> <more Python code>

        .. note:: <add a note here>
        .. seealso:: <blah>
        .. warning:: <use sparingly>
        """

Logging

See http://docs.openstack.org/developer/oslo.i18n/guidelines.html

# Do not use "%" string formatting
# No localization for debug
LOG.debug("... %s", variable)
LOG.info(_LI("... %s..."), variable)
# Use named interpolation when more than one replacement is done 
LOG.info(_LI("... %(key)s ..."), {'key': 'value', ...})
LOG.warn(_LW("... %(key)s"), {'key': 'value'})
LOG.error(_LE("... %(key)s"), {'key': 'value'})
LOG.critical(_LC("... %(key)s"), {'key': 'value'})

Designate/Development/StyleGuide

Contents

Designate Style Guide

File header

Docstrings

Logging