Lets suppose that you’re writing a program that controls whether something is either on or off. You’ve got a boolean variable or a bit flag value to control the state of this gizmo. You might be tempted to call it something like “gizmoOnOff”. Don’t do that; it’ll make your code look stupid.
For an example as to why you shouldn’t, I’m going to use C for the programming language and define a bit flag. Also, I’ll be using English as the human language. All of this still holds true for other combinations.
Here is a hypothetical data structure where the problem starts:
struct ControlFlags {
int gizmoOnOff : 1;
// other flags, too, but only one for this example
};
Later, that data structure will be used. This is where the name is all wrong:
struct ControlFlags cf;
// assume the above is now useful . . .
if (cf.gizmoOnOff)
// . . .
One part of writing good code is attempting to write it in a self-explanitory way. The more naturally the code reads, the better. In the example, the program seems to be checking if the gizmo is in the “OnOff” state. Is it on-off? What does that mean? That the gizmo is either on or off? If so, what state can it have that is neither on nor off? Is it Schrödinger’s Gizmo?
cf.gizmoOnOff = 0; // gizmo in a superposition state? or not?
Almost certainly a superposition state is not what was meant, but what state is meant by a cleared flag? Is it on or off? With both in the name, the code does not provide an answer. If the programmer meant for a set flag to indicate that the gizmo is on, then the name should be “gizmoOn”:
if (cf.gizmoOn)
// . . .
This code is very clear about what it is checking because it is much more self-explanitory. It reads almost like it is written in English; it clearly checks for the on state. Anyone reading that code will not have to make assumptions about how the value of gizmoOn is used to understand the code. Such assumptions are not always correct, and they should be avoided in anything as technical as a computer program. Take for example flags for buttons:
struct Buttons {
int aUpDown : 1;
int bUpDown : 1;
};
You might assume that if aUpDown is set that the button is pressed; that seems to be the common assumption among people who work on software. Or you may figure that since up comes before down in the name that a set flag indicates the button is up. There is software out there that indicates a pressed button with a set flag, but hardware often indicates that same state with a cleared flag. For instance, read out the data from an old NES or Playstation controller when no buttons are pressed and all the button flags will be set. In this case, naming a button flag something like “aUp” makes this clear and helps prevent others looking at the code from making the wrong assumption.
Naming the flag with only one state will also prevent someone from making fun of you by asking something like “Why is this check here since the button cannot be up-down?” or “So I set this flag to turn the gizmo on-off, and clear it to turn it . . . into a unicorn?” I suppose that is better than transforming the gizmo into Unicron.
