Unlike graphical user interfaces, developers don’t interact with APIs in a direct manipulation style through widgets or UI controls. Instead, the developer types some text into a text editor and then, some time later, compiles and runs the program. The developers don’t interact directly with the API, but rather interact directly with the tools they use to write and run the code. Obviously the usability of these tools will have a great impact on the developer’s ability to write and run code that uses the API.
But is it OK to stop there? What if, in an ideal world, the tools were the perfect tools for a developer? Would the experience that the developer has writing and running code that uses an API also be perfect? Let’s consider the impact a badly designed API has on a developer trying to use it, even with the ideal set of tools.
APIs are supposed to increase a developer’s productivity by providing components that perform common tasks. Indeed, many times a developer must use an API to accomplish some task because doing so is the only way to access encapsulated system functionality that can’t be implemented from scratch. Even when the operations can be executed without the special privileges to reach into hidden parts of the system, using the API saves the developers the time and effort required to create their own implementations of these components. Unfortunately, when an API is badly designed, it can be difficult to determine whether the time saved in using the API is worth the investment of effort in using it.
Alan Blackwell presented a model for describing how to determine whether the investment in programming a custom solution instead of using a predefined API is worth the effort [Blackwell 2002]. In the model, the developer estimates the cognitive cost of using the API as well as the cost of figuring out how to use the API. He then weighs these costs against the payoff, the potential savings in time and effort that he will accrue by using the API. The model takes into account the possibility that no such payoff will result.
To perform such an analysis, the developer uses cues in the API design such as class names, method names, and documentation to estimate the cost involved. Particular design patterns employed in the API might be recognized by the developer, and these might help him better understand how to use the API. The developer may have had experience with other parts of the API, which might suggest a particular approach to take. Additionally, the developer’s own understanding of the domain in which he is working provides another perspective on the API. The combination of API cues, design patterns, prior experience with the API, and domain understanding helps the developer estimate the effort involved to implement a solution. From this, he can decide whether or not to use the API.
However, many things can prevent the developer from making an accurate estimate of the effort required:
Class names and documentation obviously can be misleading and inaccurate. They can suggest that the API behaves in one way, even if it actually behaves in another. Martin Robillard indicated that one of the biggest obstacles to learning an API is the lack of good resources that describe the API and how it works [Robillard 2009].
Another common problem with names is that they can have multiple meanings. Determining the specific meaning often requires an understanding first of the conceptual model underlying the design of the API.
Prior experience with other parts of the API might not indicate how other parts of the API will work, particularly if design guidelines have not been followed consistently throughout the design.
The way that the developer thinks about the domain may well be very different from the way that the API represents the domain.
Unfortunately, the developer can rarely tell right away that an API is inconsistent, has poorly named classes and methods, or represents the domain differently from the way he expects. A big problem in estimating the costs involved in using an API is that the developer often has to go through the effort of creating and running a small program that uses the API before he can estimate the costs involved in creating and running a larger program that uses the API. Only once he has started writing some code that uses the API do all the idiosyncrasies and quirks in the API’s design become apparent.
Crucially, this effort is an added burden to the effort the developer had already estimated he would spend in using the API, and can quickly exceed the estimated costs of implementing a custom solution. Thus, developers may feel that instead of increasing their productivity, the API has actually made them less productive.
Hence the explosion of online forums, websites, and blogs devoted to helping developers understand the costs involved in using an API. Sites such as StackOverflow.com allow the developer to post questions and read answers about performing specific tasks with an API.
The end result is that developers often can’t figure out how to use the API, and instead of writing code and being productive, they end up spending their time browsing online forums, posting questions and reading answers. Their self-esteem takes a hit. The developer feels that all she is doing is repeatedly crafting search queries for online forums and copying and pasting code she finds online. It doesn’t really feel like she is “programming” anymore.
Even perfect tools can’t compensate for a badly designed API. Tools can help developers write and run code, but a lot of the effort in using a badly designed API is cognitive effort. The developers have to think about the best way to translate their intentions into a particular incantation of different classes and methods. Debuggers and other such analysis tools can help the developers recognize more quickly that there is a mismatch between the way that they understood or expected the API to work and the way that it actually works. But the developers still need to process the information from the tools. And the more mismatches that occur between the API and the developers’ expectations, the more mental processing the developers need to do to overcome them.
In contrast, a well-designed API allows developers to make accurate estimates of the investment required to use the API. The names used in the API effectively communicate the purpose of the classes and methods to the developers. The classes and methods in the API map well to the classes and methods that the developers expect to find in the API. The way that these classes and methods work is consistent with the way that other parts of the API work. The developers are able to get into “the zone,” and the code that they write flows naturally from their thoughts to the screen. Even if the tools that the developers use aren’t optimal, they can still have a great experience with the API because the developers don’t depend as much on the tools as they do when working with a badly designed API. In an ideal world, the tools really just let the developer type in and run their programs.