Application Programming Interfaces (APIs) play a crucial role in modern software development, acting as abstract building blocks that allow engineers to focus on what makes their programs unique without having to constantly Òreinvent the wheelÓ. While API authors convey how a method should be used via documentation, the text is delocalized from the source code that invokes that method, so its consumption requires additional effort from users of the API.

This dissertation presents the notion of "directives", important clauses in the documentation of some methods that demand action or attention from their callers. It then demonstrates via a lab study that developers who are writing or examining code invoking these methods may fail to notice these clauses in the documentation text, or even to read the text at all. This lack of awareness precludes subjects from resolving bugs in our study and may cause serious faults in real world scenarios. This problem is particularly severe in polymorphic situations.

The thesis of this dissertation is that by overlaying visual cues on particular function calls in the source code, we can make developers aware of the presence of directives in the documentation of the call targets. Further, by listing them explicitly when this text is read, we can increase the prospects of the directives actually being consumed. These interventions would not significantly distract users.

To validate this thesis, we created eMoose, a plug-in for the Eclipse IDE that realizes these techniques. We loaded it with a set of directives that were found in a systematic survey of the Java standard library. In our lab study, the tool increased awareness of the directives without significantly distracting its users.

This work provides three primary contributions to software engineering. First, it reveals a weakness in the usability of API documentation that can lead to severe errors in the use of these APIs. Second, it demonstrates that decorating links is an effective and non-distracting way of making users aware of delocalized information. Third, it demonstrates that a similar problem of knowledge delocalization may occur in software design as a result of the representational choices made by designers.

317 pages

Return to: SCS Technical Report Collection
School of Computer Science homepage

This page maintained by reports@cs.cmu.edu