Exploring the Impact of Source Code Linearity on the Programmers Comprehension of API Code Examples

TL;DR

The paper investigates how API code example structure—specifically linearity and length—affects programmers’ comprehension and reuse of API code. It uses an online controlled study with 61 Java developers evaluating Joda-Time examples across linear and non-linear, short and long variants, measuring reaction time, correctness, and subjective ratings. Findings show linear code leads to faster comprehension and reuse, with limited impact on correctness or subjective judgments, and significant differences between linear-short and linear-long variants, suggesting that linearity mainly aids initial understanding and reuse potential. These results offer practical guidance for API documentation and code example design, while highlighting the need for broader replication across APIs and environments to confirm generalizability.

Abstract

Context: Application Programming Interface (API) code examples are an essential knowledge resource for learning APIs. However, a few user studies have explored how the structural characteristics of the source code in code examples impact their comprehensibility and reusability. Objectives: We investigated whether the (a) linearity and (b) length of the source code in API code examples affect users performance in terms of correctness and time spent. We also collected subjective ratings. Methods: We conducted an online controlled code comprehension experiment with 61 Java developers. As a case study, we used the API code examples from the Joda-Time Java library. We had participants perform code comprehension and reuse tasks on variants of the example with different lengths and degrees of linearity. Findings: Participants demonstrated faster reaction times when exposed to linear code examples. However, no substantial differences in correctness or subjective ratings were observed. Implications: Our findings suggest that the linear presentation of a source code may enhance initial example understanding and reusability. This, in turn, may provide API developers with some insights into the effective structuring of their API code examples. However, we highlight the need for further investigation.

Figures (2)

• Figure 1: The time spent on (a) comprehending, and (b) reusing the API code examples used in the study. Each boxplot represents the responses for one version (linear or non-linear) of a single example.
• Figure 2: Participants' subjective ratings of API code example comprehension (a) and reusability difficulty (b).