From 2b144a7e024f1bcf1ad71b58a1371c49e573e0b0 Mon Sep 17 00:00:00 2001 From: EdLeafe Date: Thu, 15 Dec 2016 21:36:15 +0000 Subject: [PATCH] Add guidelines for boolean names This patch adds guidelines for naming boolean fields and parameters. Closes-Bug: #1593311 Change-Id: I048195d027b58c765af3cab2d9be8b03b9e7a2b7 --- guidelines/naming.rst | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/guidelines/naming.rst b/guidelines/naming.rst index 0656f31..4d7b0b6 100644 --- a/guidelines/naming.rst +++ b/guidelines/naming.rst @@ -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.