Name the Condition Rather than Resulting Action [VD8]
Tip VD8
Prefer naming a boolean variable based on the underlying condition, rather than an action that may result from the condition. This more accurately communicates the value the variable holds and avoids loss of information for the underlying condition that might result in some action in the code.
Example for an If Statement
Underlying Theory - What is Most Important When Naming a Boolean?
There’s deeper theory behind this advice to name a boolean based on the underlying condition instead of the resulting action.
At an abstract level, you can look at conditional statement code in the following way:
const bool condition = (logic that makes up the condition);
if (condition)
{
// Action resulting from condition.
}There are 3 components that could contribute to what the boolean variable represents:
The actual check of the condition variable in the if statement.
The logic that is evaluated to determine the value of the condition.
The action resulting from the condition.
The list is above is ordered so that (1) what tends to most accurately represent the meaning behind the boolean variable and (2) what tends to be most important in comprehending programs is earlier.
Programs are frequently composed of conditional logic - "if this, then do that." This is the meat and essence of many programs - we're trying to do different things based on some detected condition. The fact that we even have to use a variable is more of a non-essential limitation of programming languages - a well-named variable just happens to be the most effective way to express this condition for other humans. Thus, the condition is the most important aspect that should be taken into account when naming a boolean variable.
The next item worth considering is the logic that makes up the condition. This is worth considering because whatever makes up this logic says something about what the boolean condition represents, and it's often just a less human-readable way to express the condition. However, sometimes this logic can diverge quite drastically from the actual condition a programmer is intending to represent and check, and accurately representing the intent is more important - the intent being correctly implemented is one of the key contributors to whether a program works correctly or not.
The last item is the specific action resulting from the condition. This is the least important consideration and can often be disregarded for many boolean conditions. Even looking at the code itself, the "distance" of the action (which may be significantly more code) from the boolean condition is typically greater from other components, which automatically suggests it is less relevant to the boolean variable name.
Additional rationale behind favoring naming booleans like this for the underlying condition, rather than resulting action:
Naming the boolean variable based on the condition tends to more accurately express the "what" in the problem domain, whereas naming the boolean variable after the action would connect it more to the "how" of how a program responds to a given condition.
When a boolean variable is named after a condition, then someone reading the code should be able to tell if the action taken based on that condition makes logical sense. If the boolean variable name were named after the action, then the condition information would be lost, which means that all a reader could easily check to verify code correctness would be making sure the boolean variable named after the action matches the actual code implementing the action. This action-based name would not support making sure that the code is behaving correctly at the high, macro level that would matter to users.
Importance of Naming the Underlying Condition for Loops
Naming booleans based on the underlying condition, rather than resulting actions, can become more important in loops:
while (!file.AtEndOfFile())
{
// ...
}With loops, it is incredibly important for a reader to be able to understand the conditions in which the loop body will execute. The loop body may be very long and complicated - you don’t want the reader to have to try and read all of that code to figure out what controls execution of the loop. Treating the body of a loop as a “black box” can help with this thinking. When looking at code from the top-down, you want to make sure the control flow - including all of the various conditions that might affect it - are clear. That way, when readers need to see what happens in response to a given condition, they can then narrow down to just the actions taken into response to the particular condition they're interested in.
Conclusion
Summarizing the resulting actions for conditional statements and loops can be important, but that information is typically better communicated in comments before the control structures to avoid a loss of insight into the actual code.