Use of "Create-Set-Call" vs "Required Constructors" in LabVIEW

[cbutcher]

A usability study published by Jeffrey Stylos and Steven Clarke titled Usability Implications of Requiring Parameters in Objects' Constructors discusses a comparison of two methods of Object construction and their relative merits - it concludes that what they term the "Create-Set-Call" method is preferable for almost all users of an API.

In LabVIEW terms, this is something like dropping a default object constant to the block diagram, then calling a series of "Write Property A", "Write Value B", "Set Init Properties" or similar methods.

The "Required Constructor" syntax would presumably be something more like placing the class inside a library as a private member, then providing a public VI which output an initialized version of that class' object having already called those "Write ..." VIs on the class member (taking as arguments the required values, probably as "required" inputs).

The participants in the study are noted as giving feedback as follows (in favour of C-S-C): 

Less restrictive: In general, APIs should let their consumers decide how to do things, and not force one way over another.

My question becomes - is this true? Should an API allow programming mistakes that can be avoided by forcing specific operations via (in LabVIEW) access control?

A similar example (not discussed in the paper) would seem to be the Template Method (wikipedia, NI implementation), in which some parts of the API are restricted from the user (in my case, often still me) in order to enforce some specific usage. Why is this inherently different? Just because it looks like a normal method from the outside?

[tyk007]

The "Create-Set-Call" terminology seems to extend far into the bowels of Microsoft as far as I can tell - it has existed since at least 2004 in the Framework Design Guidelines if not older. My interpretation of their (Microsoft) guidance to expose a API with that level of flexibility is to permit a client to use only the parts they need in order to improve learning and adoption

• It makes sense for a large, complex API such as a .NET frameworks that deal with many different objects. The odds of creating an API with an enforced flow of control that suits all needs starts to diminish.
• Once an API is established it is hard to make changes without breaking existing consumers. An API with a rigid flow of control can make things more difficult in this scenario, especially if parts of the API require obsolescence.
• Their guidelines also state that the intent is for the API to expose objects for the common use cases to speed up adoption but that the object should also provide feedback to a caller if they have forgotten to configure the object correctly. 

In the context of LabVIEW - frameworks are never that large nor that complex. As a client of an API you'd be lucky to deal with a handful of objects let alone hundreds. So it I think it is very reasonable to provide custom constructors with the common use cases (that write to the object fields appropriately) but to also expose, if needed, the individual properties themselves. 

Another way to look at this is to let each method of an object define what its highly volatile dependencies. An example could be timeouts - this is something the caller is highly likely to tweak and could be exposed on the method connector pane. The object could still have defined private data but this data is either client configuration that they would not typically want to tweak once set or data the object needs to perform its work in which case it is not exposed to the client.

[wiebe@CARYA]

---

@cbutcher wrote:

 it concludes that what they term the "Create-Set-Call" method is preferable for almost all users of an API.

---

Guess it depends on what constitutes an API. I don't think this CSC would be useful for just any class. It would be pretty stupid to force a user to put 5-10 individual "set" vi's after each other if they're all required to be set.

If you can instantiate a class, and all it's settings are optional (e.g. the object by default does something useful), then it makes sense.

I guess the first situation might be more typical for LabVIEW classes, and the second situation is more typical for the more reusable API's. That is what I see in my classes.