Understanding initial API comprehension

Programmers encounter new Application Programming Interfaces (APIs) regularly as a part of their work. Difficulties in API comprehension affect programmers' performance and the quality of the software they produce. To effectively support API comprehension, it is important to understand how programmers comprehend new APIs in real-life work contexts. In this study, we explore programmers' initial API comprehension efforts. We analyze what information programmers need about an API before they are ready to start working with it and the actions and information sources they use to acquire this information. Furthermore, we identify different contextual factors that affect this process. We used the critical incident method to interview programmers about their API comprehension processes in work contexts. Our results show that before our participants were ready to start using an API for a task, they sought information about the API from various sources to assess its validity and evaluate it with respect to the requirements of the task. They used their background knowledge to steer their information-seeking efforts and to recognize key pieces of information that strengthened or weakened their confidence in the suitability of the API for the task at hand. As initial API comprehension and the resulting initial API mental models seem to guide further stages of programmers' API comprehension efforts, they heavily influence the direction of the rest of the comprehension process. Therefore, it should be considered in the design of means to support API comprehension, such as API documentation.