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 <[email protected]> Authored: Mon Dec 30 15:24:53 2013 +0100 Committer: Tomaz Muraus <[email protected]> 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
