openstack/api-sig
Code Issues Proposed changes

Add guidelines for boolean names

Browse Source 
This patch adds guidelines for naming boolean fields and parameters.

Closes-Bug: #1593311

Change-Id: I048195d027b58c765af3cab2d9be8b03b9e7a2b7
This commit is contained in:
EdLeafe 2016-12-15 21:36:15 +00:00
parent e01a677e96
commit 2b144a7e02
1 changed files with 29 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
guidelines/naming.rst
View File

@ -34,6 +34,34 @@ according to these guidelines:
* Field names should use `snake_case` style, *not* `CamelCase` or `MixedCase`
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.
**TODO** Add patch proposing guidelines for naming state/status fields.