Architexa - Understand and Document  

Labs - Code Understanding via Exploratory Tools

Note: This document represents the main ideas of work done earlier in our labs. The tool has since had major updates and is currently in beta. Contact us at for more information.
Vineet Sinha, Architexa
Rob Miller, MIT CSAIL
David Karger, MIT CSAIL

Code Relationships via Class Diagrams

Summary: As software systems grow in size and use more third-party libraries and frameworks, the need for developers to understand unfamiliar large codebases is rapidly increasing. We present a tool, Relo, that supports users’ understanding by allowing interactive exploration of code. As the developer explores relationships found in the code, Relo builds and automatically manages a visualization, similar to a UML Class Diagram, mirroring the developer’s mental model, allowing them to group viewed artifacts or use the viewed items to ask the system for further exploration suggestions.

Publication: “Incremental exploratory visualization of relationships in large codebases for program comprehension”. In the 20th Annual ACM SIGPLAN Conference on Object-Oriented Programming, Systems, Languages, and Applications OOPSLA '05. ACM. [link]

Keywords: Program Comprehension, Software Visualization, Large Software Systems.


Working with the complexity of large software projects is a pervasive and growing problem. Developers face increasing difficulties in comprehending and maintaining a mental model of the code in large codebases. While techniques like object-oriented programming and design patterns have helped control complexity by allowing developers to create and use appropriate abstractions and encapsulate inessential details, these techniques require a developer reading the code to follow many kinds of relationships at once. For example, following a function call, once a simple task, now also requires keeping track of inheritance and polymorphism.

Relo is a program comprehension tool which helps developers to understand the roles of the multiple types of relationships in a software system. Relo visualizations start with a single code artifact (such as a package, class, or method), from which a user can browse the different types of relationships to incrementally add more code artifacts. Relo helps maintain context while users manage the visualization by choosing to remove or group artifacts together. Such visualizations, like concern graphs [ref], represent only a small manageable part of the code and do not include irrelevant details allowing a user to focus on the important relationships.

Relo visualizations try to be intuitive to end-users, showing code artifacts in diagrams similar to UML Class Diagrams, while at the same time allowing developers to zoom in to view and edit code using text editors embedded in the graph. Developers can therefore abstract to a high level, or zoom-in to see code. Relo further helps maintain users’ focus by providing explicit support for exploration while managing the amount and presentation of information to the user based on his/her interaction with code elements.


Figure 1: Relo started
by opening EllipseFigure

Figure 2: After adding the
method basicMoveBy

Figure 3: Clicking on the class
to show the handles on it

Figure 4: Clicking on the
inheritance handles

Consider the scenario (as mentioned in [ref]) of a user trying to understand a portion of the JHotDraw project (link), which lets users draw a variety of figures including lines, triangles, rectangles, etc. Let us trace through the steps of a developer trying to understand how to operate on figures. The developer starts by examining a package called figure that seems related to the task and is one of the small number of packages in the project. The developer continues by opening the class EllipseFigure in Relo.

On starting Relo with EllipseFigure the user is presented with Figure 1. The figure shows that the class has 15 members, and the user clicks on the menu to see a list. Considering the method ‘basicMoveBy’ as potentially interesting, he clicks on the method name in the menu and thereby adds the method to the diagram (Figure 2). Once added the user clicks on the class and is presented with a vertical handle indicating the class inherits from another class (shown in Figure 3). At a glance the user knows that the no other classes inherit from it, and notices that he is provided with handles for expanding, shrinking, or removing the class. The user continues his exploration by clicking upwards through the superclasses (Figure 4).

Figure 5: Expanding the class AbstractFigure and the
method addFigureChangeListener

Figure 6: Asking for callers of addFigureChangeListener

At this point in time the user has an idea of the inheritance tree of figures in the project, and he can choose to expand the topmost class with an implementation. After double-clicking to see all public methods and remove irrelevant methods, the user decided to expand the addFigureChangeListener method, as it seems to be part of the general framework for changing figures.

The user is presented with the Figure 5, which shows the implementation of the method. A simple option will be to collapse the class AbstractFigure and to examine a caller of addFigureChangeListener. On clicking the caller handle on the base class, Relo continues to build the graph (shown in Figure 6), and has begun to act as both a call-hierarchy browser and an inheritance-hierarchy browser. Unlike previous graphical or tree widget based exploratory approaches used in most IDE’s, all the relationships are being shown by Relo in one place instead of having separate views for each relationship. Additionally, the diagram only shows the queried-for code elements and does not need to make visible all the other classes in the shown packages, as would be done by tools only supporting expansion via visual containment [ref]. Finally, the diagram shows some unexpected relationships, such as some calling methods belong to the same class, an observation that would not have been possible by showing the relationships and code elements in a single tree widget as done by Janzen et al. [ref].

The user can further continue using Relo, as the tool goes on to build a larger visualization in order to supplement the user’s understanding of the codebase.

Make sense of your code now! Get Started
Architexa is an i3labs project. Copyright ©2017 i3labs. All rights reserved. Privacy Policy | Terms of Use