Naming conventions for set/unset method parameter

Question

I have some class MyClass which has two methods:

Lock(){}
Unlock(){}

For some reasons, the two methods are to be unified into one, with an additional parameter for indicating the action. What should be the name of the parameter?

SetLockState(bool isLock)
SetLockState(bool isLocked)
// or another better name? 

This happens a lot in our code base. I favor isLock, because it is the new state, but it seems there is some convention about isLocked which I am unfamiliar with.

I would love an explanation as to why isLocked is the standard. And I would like to know if there is any objective argument that can support the choice of the parameter name.

Answer 1

The most important is that the method name reflects a behavior. You do this perfectly well with the Set prefix (if your project indeed doesn’t use lower camel case for method names).

The consumers would then write something very unambiguous and self-documenting:

myobject.SetLock(true);     

As a consumer, I perfectly understand that the parameter name in your interface definition reflects the intended target state that will result from the operation:

SetLock (boolean isLocked);

For the maintainers of this class, the name of the parameter will probably be understood the same way. You just should avoid any confusion with the internal state. It is nevertheless true that the readability and clarify of the implementing code will have ups and downs:

internallyLocked = isLocked;     // rather clear
if (isLocked) { ... }            // rather ambiguous 

If you want to improve that readability, the problem of your name is not so much the ending of your parameter but its beginning. In all objectivity:

• if the parameter starts with is, the end should be locked for the sake of grammatical consistency;
• is prefix suggests a current state when used in the method body. If you want to avoid any potential ambiguity, you could use a less ambiguous prefix to clarify the intention: either reflect a change of state, or a target state.

The exact choice of wording is opinion based. I could think for example of toBeLocked (target state clearly expressed) or willLock (change action clearly expressed). The latter has the advantage that it belongs to the usual prefixes (is, has, can, will, was, did) But there are certainly many other possibilities that comply with these basic principles.

Answer 2

I recently brought to a discussion similar to this the analogy of a ceiling lamp.

Consider someone asks you to turn the lights off. What do you do?

1. Look at ceiling.
2. Is the lamp on?
   1. Press the switch on the wall.
3. Say done.

What you are asking is what action did I do with the switch?

• You could simply say you pressed it, and therefore the name press is ok as the method name.
• You could also say you toggled the state of the switch, and therefore the name toggle is ok as the method name.

Toggle, however, conveys a bit more information. Toggle associates with state, you toggle between two states. On and Off, in the case of the light bulb.

What you did not do, in the literall sense, was turning off the lamp. You toggled the switch to control the electricity that goes in to the lamp. You could have pressed a switch for another lamp, for example.

So you checked the state of the lamp to decide whether to press the switch. Therefore state is a concept of the lamp; press is concept of the switch; toggle is a concept of the ceiling lamp system.

In conclusion, different terms are appropriate in different contexts of a system. And the correct usage of terms in the correct context is what you are looking for.