From 5a739ed901cd1dd1910faed26fcc9c7bbb60f305 Mon Sep 17 00:00:00 2001 From: jeff Date: Mon, 27 Jul 2020 11:29:30 -0700 Subject: [PATCH] checking in --- content/blog/boolean_names.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/content/blog/boolean_names.md b/content/blog/boolean_names.md index 2005f58..57cc402 100644 --- a/content/blog/boolean_names.md +++ b/content/blog/boolean_names.md @@ -15,18 +15,20 @@ The book, _The Elements of Style_ 1, is a concise guide to writing En In English, it is best to use enabled or disabled, and to avoid "not enabled"; they are more concise and stay in the positive form. The extra requirement of using a positive statement for boolean names is because boolean variables' negations have meaning as well; in writing "not disabled" is a double negative and is discouraged. In code, '!disabled', is also a double negative, and should be avoided. -A boolean name should give the reader more clarity as it's scope expands. In [Go](https://play.golang.org/p/i1W05p5EpAN), a boolean variable that exists for the scope of an if statement may have a short name ('ok'). If this variable was in scope throughout the function, it would become meaningless. +A boolean name should give the reader more clarity as it's scope expands. A boolean variable that exists for the scope of an if statement may have a short name ('ok'). If this variable was in scope throughout the function, it would become meaningless. ## Bad Boolean Names As with many things in software engineering, it is easier to find mistakes than to do something correctly the first time. Here are some naming conventions to avoid: -1. Names that are already a negation. 'notReady' and 'notProd' may make sense in one use case, but becomes confusing in a larger context. This can lead to code such as, `confA.useUAT = !confB.notProd`. This is both hard to read and ambiguous (what if there is a third environment). +1. Names that are already a negation. 'notReady' and 'notProd' may make sense in one use case, but becomes confusing in a larger context. This can lead to code such as, `confA.useProd = !confB.notProd`. This is both hard to read and ambiguous (what if there is a third environment). 2. Names that are not negatable. A name such as, 'sheets', has ambiguous meaning. It probably has something to do with a spreadsheet, but it is the writer's responsibility to prevent the reader from needing to do an investigation. -3. Names that are in negative form. These usually appear when the typical behavior is the negative form. For example, 'disabled'. Keep all the names in positive form to avoid a future headache explaining what the billing system does when it's "not disabled". Is it enabled, or is it just not disabled? +3. Names that are in negative form. These typically appear when the default use is the negative form. For example, 'disabled' for a service typically disabled. Keep all the names in positive form to avoid a future headache explaining what the billing system does when it's "not disabled". Is it enabled, or is it just not disabled? 4. Overly general names. As discussed earlier, this depends on the scope of the name. Avoid using a name such as, 'on'. It leaves questions in the reader's mind such as, "What is on?". The exception to this is typical boolean names used across code bases; Go's 'ok' is an example of this. +5. Negatable adjectives without context. 'bool customSize' is clear, but without the 'bool' context, the type is unclear. Ambiguity can be removed by prefixing 'is' or 'has' ('isCustomSize'). + ## Conclusion This blog post discussed a goal to aim at (good names), and several things to avoid (bad names). Combined, these will hopefully increase the readability of your software!