Details the proper way to call a callable

Change-Id: I288822ed3aa8a755fc90fbf7940da043995cb719

1 files changed, 20 insertions, 0 deletions

diff --git a/HACKING.rst b/HACKING.rst
index 76ba2ba08..6b4181121 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -36,3 +36,23 @@ AssertEqual argument order
 --------------------------
 
 assertEqual method's arguments should be in ('expected', 'actual') order.
+
+
+Properly Calling Callables
+--------------------------
+
+Methods, functions and classes can specify optional parameters (with default
+values) using Python's keyword arg syntax. When providing a value to such a
+callable we prefer that the call also uses keyword arg syntax. For example::
+
+    def f(required, optional=None):
+        pass
+
+    # GOOD
+    f(0, optional=True)
+
+    # BAD
+    f(0, True)
+
+This gives us the flexibility to re-order arguments and more importantly
+to add new required arguments. It's also more explicit and easier to read.