Using the Cognitive Dimensions - API Elaboration

This dimension provides a measure of the extent to which developers must and can extend the API in order to accomplish a given task. As before, the first step in measuring this dimension is to do a task analysis of the main scenarios that your users will use the API for. Then, using the results of the task analysis proceed through the following:

 

For each goal that the user might attempt to accomplish with the API describe the extent to which the user can and must extend the classes exposed by the API. List the types that the users can use directly, the types that they need to extend and the new types that they need to create. Some tasks and goals can be accomplished by using the types provided by the API. Other tasks and goals might require that the user override some default behavior in a derived class to achieve the desired functionality. Still other tasks and goals might require that the user provide a completely new type that implements some given interface, for example.

 

In the System.IO namespace, one user goal might be to write code that appends a line of text to a text file. The user can accomplish this task using the StreamWriter class exposed by System.IO. There is no need to extend this class or implement an interface in order to be able to accomplish this task.

 

API elaboration can be defined in the following terms.

 

• If the API allows users to accomplish all of their goals only by using the types exposed by the API without requiring further elaboration, the API can be used as-is.
• If the API allows users to accomplish all of their goals only by extending some of the types exposed by the API and providing their own implementation of custom behavior, the API supports elaboration at the fine tune level.
• If the API allows users to accomplish all of their goals only by replacing or introducing whole new types, then the API demands elaboration only at the replace level.

Note that an API can provide support for elaboration at multiple points on the scale. It might, for example, provide a set of components that can be used as-is for most user goals but that can also be extended or even replaced for a different set of user goals. Given this, it is vital to ensure that the API is measured against the core set of tasks that the target user would be expected to accomplish.

 

Some users do not expect to have to extend existing functionality in order to achieve their goals. Forcing these users to extend existing functionality to meet their goals will likely cause problems for them when using the API. On the other hand, some users may not feel comfortable using an API unless they are able to extend the API, should the need arise. These users look for some amount of flexibility built into the API and want to be able to fine tune the types available if required. Like the penetrability dimension, API elaboration can be described in terms of both what the API supports and what developers require. While an API may not demand that users specialize a number of classes or override a number of methods in order to be able to do any useful work, it might also be important that it does not prevent some developers from doing so, should they so wish.

 

Given the above definition of elaboration, the classes in the System.IO namespace support as-is usage. They do not demand that the user replaces or extends any components to meet their goal of appending a line of text to a text file.