Register & Unregister or just Register?

[Aristos Queue]

I have functionality where I want to fill in a table that maps one value to another value. I have named the function that adds to this table Register XYZ.vi (where XYZ is my key type). I have a second function Unregister XYZ.vi that removes a key from the table.

Register and Unregister, however, create an expectation in LabVIEW that if a user of my API calls Register that somewhere in the code he or she should call Unregister for good coding practice. But I do not expect that to be the common case. There's no need to do an Unregister the vast majority of the time -- this table is rarely unregistered item by item and instead the table itself just stops being used. And it's a by value table, not a reference whose lifetime has to be tracked.

So I am strongly contemplating just having one function "Register XYZ.vi", and if the user passes zero for the value to register, that just removes the item from the table (registering zero and not having an entry in the table are functionally equivalent).

"Register" is definitely the verb I want to use -- I gave a lot of thought about that before even asking this question, though perhaps a complete rephrasing of the name.

So my question: Which of these APIs would be, in general, more intuitive to you?

A) A Register and Unregister pair of VIs but where Unregister is almost never used and it is not considered a bug or a leak or otherwise a problem.

B) A single Register VI whose behavior when you register a particular value is to remove the item from the registration.

C) I have a third solution (please post comment below)

[mje]

So I am strongly contemplating just having one function "Register XYZ.vi", and if the user passes zero for the value to register, that just removes the item from the table (registering zero and not having an entry in the table are functionally equivalent).

Other than the obvious changes in interface, I really don't see the difference because in the end they are functionally equivalent: there exists some means of unregistering. Between these two options, I prefer an separate unregister method because it's more explicit. I know you said you're working entirely by value, but the unregister method is also somewhat consistent with the acquire/use/release paradigm that is all over the place in LabVIEW, even if that is usually for reference objects.

Now of course I can't really say if an unregister method is required. That's something that's on you. I imagine you're entertaining the idea though because you can imagine at least one use case where it would be useful...

[todd]

A

It makes me think of "build array" and "delete from array".

[Aristos Queue]

Todd: Bingo. Those names don't imply "if I use one, I'll use the other." But I'm kind of afraid that Register and Unregister do. But I really like the verb in this particular context.

[drjdpowell]

A

Seems very like the Set and Delete Variant Attributes. Also, if the table just disappears at some point, then it is perfect intuitive that I don’t have to unregister (as the registrations are part of the table).

[ShaunR]

Rather than register et al. Wouldn't be more appropriate to use "add mapping" and "delete mapping"? (in a similar vein to add to list, delete from list). That semantic is fairly universal and you yourself used "add" to describe the register.

Edited March 12, 2012 by ShaunR

[Daklu]

I'm also curious about the terminology. Why is "Register" so important? If you're stuck with that terminology I agree with mje--I'd much rather have an explicit Unregister method than magic inputs that make the Register method unregister an entry. (Besides, are you *positive* nobody will ever want to register a value of zero?)

What kind of mapping are you doing? 1 to 1? 1 to many?

[asbo]

I agree that "Register" doesn't seem like an apt verb for your method. I'm inclined toward "Map" or "Set" because neither of those have the associated cleanup paradigm that "Register" does. Given that your own description of the functionality uses the word "map", that really feels like the right choice.

However, if you truly are rooted on "Register", I would vote against a sentinel value being used to unregister - it feels backdoor and kludge-y, IMO. You could just as well as another boolean terminal for "Unregister?" which was optional and defaulted to false. I also had the thought that using "Deregister" might be far enough different from "Register"/"Unregister" that it would make a developer actually read the Context Help for the VI before slapping it down.

[Aristos Queue]

(Besides, are you *positive* nobody will ever want to register a value of zero?)

Actually, I do expect people to register zero... but zero and unregister are functionally equivalent.

[Daklu]

Actually, I do expect people to register zero... but zero and unregister are functionally equivalent.

Yeah, but are they semantically equivalent? If you were to explain the context of your api to a typical LV user would they naturally expect registering a value of zero is the correct way to unregister an entry, or would you have to explain it to them?

I still vote for symmetric calls in collections--it makes the api much easier to understand.

--- Edit ---

Here's a question for you...

Upon unregistration are you removing the entry from the table or just disabling it? I'd expect Unregister to remove the item while Register (0) would disable it but leave it in the table. (Though my preference would still be to provide specific enable/disable methods.)

Edited March 12, 2012 by Daklu

[JackDunaway]

It's helpful for the API to have two separate functions. When using "Find All Instances" in the LabVIEW IDE, it's simpler to have all "Registers" in a list and all "Unregisters" in a separate list. An "Unregister" function is more self-documenting than a "Register" with a special-super-secret argument (e.g., "I forget, do I wire -1 or 0 or NaN to unregister?...").

***Edit*** - agree with Daklu:

I still vote for symmetric calls in collections--it makes the api much easier to understand.