Merge "Add guidelines for boolean names"

guidelines/naming.rst

@@ -34,7 +34,35 @@ according to these guidelines:
 * Field names should use the `snake_case` style, *not* `CamelCase` or
   `StUdLyCaPs` style.
 
-**TODO** Add patch proposing guidelines for how to name boolean fields.
+Boolean fields
+--------------
+
+Boolean fields should be named so that the name completes the phrase "This is
+_____" or "This has ____". For example, if you need a field to indicate whether
+the item in question is enabled, then "enabled" would be the proper form, as
+opposed to something like "is_enabled". Similarly, to indicate a network that
+uses DHCP, the field name "dhcp_enabled" should be used, rather than forms such
+as "enable_dhcp" or just "dhcp".
+
+It is also strongly recommended that negative naming be avoided, so use
+'enabled' instead of 'disabled' or 'not_enabled'. The reason for this is that
+it is difficult to understand double negatives when reading code. In this case,
+"not_enabled = False" is harder to understand than "enabled = True".
+
+Boolean parameters
+------------------
+
+There are two types of boolean parameters: those that are used to supply the
+value for a boolean field as described above, and those that are used to
+influence the behavior of the called method. In the first case, the name of the
+parameter should match the name of the field. For example, if you are supplying
+data to populate a field named 'enabled', the parameter name should also be
+'enabled'. In the second case, though, where the parameter is used to toggle
+the behavior of the called method, the name should be more verb-like. A example
+of this form is the parameter "force", which is commonly used to indicate that
+the method should carry out its action without the normal safety checks. And as
+with boolean fields, the use of negative naming for boolean parameters is
+strongly discouraged, for the same reasons.
 
 State vs. Status
 ----------------