********************************
Shade Developer Coding Standards
********************************

In the beginning, there were no guidelines. And it was good. But that
didn't last long. As more and more people added more and more code,
we realized that we needed a set of coding standards to make sure that
the shade API at least *attempted* to display some form of consistency.

Thus, these coding standards/guidelines were developed. Note that not
all of shade adheres to these standards just yet. Some older code has
not been updated because we need to maintain backward compatibility.
Some of it just hasn't been changed yet. But be clear, all new code
*must* adhere to these guidelines.

Below are the patterns that we expect Shade developers to follow.

API Methods
===========

- When an API call acts on a resource that has both a unique ID and a
  name, that API call should accept either identifier with a name_or_id
  parameter.

- All resources should adhere to the get/list/search interface that
  control retrieval of those resources. E.g., `get_image()`, `list_images()`,
  `search_images()`.

- Resources should have `create_RESOURCE()`, `delete_RESOURCE()`,
  `update_RESOURCE()` API methods (as it makes sense).

- For those methods that should behave differently for omitted or None-valued
  parameters, use the `_utils.valid_kwargs` decorator. Notably: all Neutron
  `update_*` functions.

- Deleting a resource should return True if the delete succeeded, or False
  if the resource was not found.

Exceptions
==========

All underlying client exceptions must be captured and converted to an
`OpenStackCloudException` or one of its derivatives.

Client Calls
============

All underlying client calls (novaclient, swiftclient, etc.) must be
wrapped by a Task object.

Returned Resources
==================

Complex objects returned to the caller must be a dict type. The
methods `obj_to_dict()` or `obj_list_to_dict()` should be used for this.

As of this writing, those two methods are returning Bunch objects, which help
to maintain backward compatibility with a time when shade returned raw
objects. Bunch allows the returned resource to act as *both* an object
and a dict. Use of Bunch objects will eventually be deprecated in favor
of just pure dicts, so do not depend on the Bunch object functionality.
Expect a pure dict type.

Nova vs. Neutron
================

- Recognize that not all cloud providers support Neutron, so never
  assume it will be present. If a task can be handled by either
  Neutron or Nova, code it to be handled by either.

- For methods that accept either a Nova pool or Neutron network, the
  parameter should just refer to the network, but documentation of it
  should explain about the pool. See: `create_floating_ip()` and
  `available_floating_ip()` methods.

Tests
=====

- New API methods *must* have unit tests!

- Functional tests should be added, when possible.

- In functional tests, always use unique names (for resources that have this
  attribute) and use it for clean up (see next point).

- In functional tests, always define cleanup functions to delete data added
  by your test, should something go wrong. Data removal should be wrapped in
  a try except block and try to delete as many entries added by the test as
  possible.
