JTourBus: Simplifying Program Understanding by Documentation that Provides Tours Through the Source Code

Abstract

Many small and medium-sized systems have little or no design documentation, which makes program understanding during maintenance enormously more difficult when performed by outsiders. Thus, if only minimal design documentation is available, which form should it take to maximize its usefulness? We suggest that it is helpful if the documentation describes a tour through the source code, leading the user directly to relevant details. This work reports an evaluation of this conceptual idea in the form of a controlled experiment with 59 student subjects working on a difficult program understanding task in the context of the 27 KLOC JHotDraw graphics framework. One group received a plain text documentation, the other received tour-structured documentation which they navigated by using an Eclipse plugin called JTourBus that we constructed for the experiment. The results indicate that program understanding can be achieved somewhat faster (albeit not more correctly) with JTourBus than with a plain text document.