git commit: docs: Add a paragraph about **kwargs to the code coventions section.

[to...@apache.org]

Updated Branches:
  refs/heads/trunk b5d779266 -> df38b3b70


docs: Add a paragraph about **kwargs to the code coventions section.


Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/df38b3b7
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/df38b3b7
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/df38b3b7

Branch: refs/heads/trunk
Commit: df38b3b70b481b270deab0e0a5d9c0bcb25db1b2
Parents: b5d7792
Author: Tomaz Muraus <to...@apache.org>
Authored: Mon Dec 30 15:24:53 2013 +0100
Committer: Tomaz Muraus <to...@apache.org>
Committed: Mon Dec 30 15:24:53 2013 +0100

----------------------------------------------------------------------
 docs/development.rst | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/libcloud/blob/df38b3b7/docs/development.rst
----------------------------------------------------------------------
diff --git a/docs/development.rst b/docs/development.rst
index fac8238..30b7568 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -116,7 +116,36 @@ Bad:
 
     some_method(public_ips, private_ips)
 
-4. When returning a dictionary, document it's structure
+4. Don't abuse **kwargs
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You should always explicitly declare arguments in a function or a method
+signature and only use ``**kwargs`` and ``*args`` respectively when there is a
+valid use case for it.
+
+Using ``**kwargs`` in many contexts is against Python's "explicit is better
+than implicit" mantra and makes it for a bad and a confusing API. On top of
+that, it makes many useful things such as programmatic API introspection hard
+or impossible.
+
+A use case when it might be valid to use ``**kwargs`` is a decorator.
+
+Good:
+
+.. sourcecode:: python
+
+    def my_method(self, name, description=None, public_ips=None):
+        pass
+
+Bad (please avoid):
+
+.. sourcecode:: python
+
+    def my_method(self, name, **kwargs):
+        description = kwargs.get('description', None)
+        public_ips = kwargs.get('public_ips', None)
+
+5. When returning a dictionary, document it's structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Dynamic nature of Python can be very nice and useful, but if (ab)use it in a
@@ -127,7 +156,7 @@ If you have a function or a method which returns a dictionary, make sure to
 explicitly document in the docstring which keys the returned dictionary
 contains.
 
-4. Prefer to use "is not None" when checking if a variable is provided or defined
+6. Prefer to use "is not None" when checking if a variable is provided or defined
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When checking if a variable is provided or defined, prefer to use