I just finished up an API usability study, during which one of the issues that came up was due to the API suffering from premature commitment (see one of my earlier postings on what this is).

In the API we looked at last week, users could create certain objects and add them to a collection of those objects. The collection represented relationships between the object that owned the collection and all of the objects in the collection. Each new relationship needed to be named every time the user added one to the collection. In other words, every time a participant wanted to relate object X with object Y, they would call something like:

objectX.Add(objectY, “Name of the relationship“);

During the study, when participants initially wrote code to create and add new relationships they had no idea what to name them. They needed to be able to think ahead and consider all of the relationships that they might add to this object and how they would be able to distinguish between each of them. If they weren't sure what type of relationships they would be adding to the collection now and in the future, they had difficulties working out what would be a good naming scheme. Almost invariably, participants needed to make changes to the naming scheme later on, requiring participants to concentrate more on 'administrative' issues as opposed to the business logic that they were trying to implement.

In this case, the relationship names simply need to be unique. But it can be pretty difficult to think of a naming scheme that you can guarantee will be unique when you don't know the complete set of items that will be named. The resolution in this example was to remove the requirement for users to name the relationships and have the implementation assign some unique ID to each relationship as they are added.