naming a function that exhibits "set if not equal" behavior

This might be an odd question, but I'm looking for a word to use in a functi开发者_开发技巧on name. I'm normally good at coming up with succinct, meaningful function names, but this one has me stumped so I thought I'd appeal for help.

The function will take some desired state as an argument and compare it to the current state. If no change is needed, the function will exit normally without doing anything. Otherwise, the function will take some action to achieve the desired state.

For example, if wanted to make sure the front door was closed, i might say:

my_house.<something>_front_door('closed')

What word or term should use in place of the something? I'd like it to be short, readable, and minimize the astonishment factor.

A couple clarifying points...

I would want someone calling the function to intuitively know they didn't need to wrap the function an 'if' that checks the current state. For example, this would be bad:

if my_house.front_door_is_open():
    my_house.<something>_front_door('closed')

Also, they should know that the function won't throw an exception if the desired state matches the current state. So this should never happen:

try:
    my_house.<something>_front_door('closed')
except DoorWasAlreadyClosedException:
    pass

Here are some options I've considered:

my_house.set_front_door('closed')
my_house.setne_front_door('closed') # ne=not equal, from the setne x86 instruction
my_house.ensure_front_door('closed')
my_house.configure_front_door('closed')
my_house.update_front_door('closed')
my_house.make_front_door('closed')
my_house.remediate_front_door('closed')

And I'm open to other forms, but most I've thought of don't improve readability. Such as...

my_house.ensure_front_door_is('closed')
my_house.conditionally_update_front_door('closed')
my_house.change_front_door_if_needed('closed')

Thanks for any input!

---

I would use "ensure" as its succinct, descriptive and to the point:

EnsureCustomerExists(CustomerID)
EnsureDoorState(DoorStates.Closed)
EnsureUserInterface(GUIStates.Disabled)

---

Interesting question!

From the info that you have supplied, it seems to me that setstate (or simply set, if you are setting other things than states) would be fine, though ensure is good if you want to really emphasize the redundancy of an if.

To me it is however perfectly intuitive that setting a state does not throw an exception, or require an if. Think of setting the state of any other variable:

In C:

int i;

i = 5;  // Would you expect this to throw an exception if i was already 5? 

// Would you write
if (i != 5)
    i = 5;
// ?

Also it only takes about one sentence to document this behaviour:

The function does nothing if the current state equals the requested state.

EDIT: Actually, thinking about it, if it is really important to you (for some reason) that the user is not confused about this, I would in fact pick ensure (or some other non-standard name). Why? Because as a user, a name like that would make me scratch my head a bit and look up the documentation ("This is more than just an ordinary set-function, apparently").

EDIT 2: Only you know how you design your programs, and which function name fits in best. From what you are saying, it seems like your setting functions sometimes throw exceptions, and you need to name a setting function that doesn't - e.g. set_missile_target. If that is the case, I think you should consider the set_if, set_when, set_cond or cond_set names. Which one would kind of depend on the rest of your code. I would also add that one line of documentation (or two, if you're generous), which clarifies the whole thing.

For example:

    // Sets missile target if current target is not already the requested target, 
    // in which case it does nothing. No exceptions are thrown.
    function cond_set_missile_target ()
or  function cond_set_MissileTarget ()
or  function condSet_MissileTarget ()
or  function condSetMissileTarget ()

ensure is not so bad, but to me it implies only that there is additional logic required to set the state (e.g. multiple states tied together, or other complications). It helps to make the user avoid adding unnecessary ifs, but it does not help much with the exception issue. I would expect an ensure function to throw an exception sooner than a set function, since the ensure function clearly has more responsibilities for, well, ensuring that this setting operation is in fact done right.

---

I'd go for ensure for the function you describe. I'd also use camelCase, but I suppose you may be in a language that prefers underscores.

You could always document (shock!) your API so that others don't make the mistakes you describe.