Exploration and Complexity Management in Graph-Based Programming Environments

We define graph-based programming environments (GBPEs) as a type of programming environment that uses a graph structure to represent code and relationships between code fragments. GBPEs can be seen as an extension to typical computational notebooks, which are linear documents that contain code, documentation, and visualizations; typical computational notebooks present code in one dimension, whereas GBPEs present code in two dimensions. An interesting middle ground between computational notebooks and GBPEs is discussed in “Exploring Organization of Computational Notebook Cells in 2D Space” [20], where Harden et al. explore the benefits of organizing computational notebook cells in a 2D space. The 2D layout affords non-linear code narratives and admits a form of branching not supported by conventional Notebooks. Their user studies reveal that users indeed take advantage of the 2D structure and that the layout promotes exploratory programming.

Another example of reorganizing code fragments in a 2D layout is Code Bubbles [10]. Code Bubbles is a programming environment that organizes code fragments in a 2D space, allowing developers to group and organize code bubbles in various ways. The evaluation shows that the approach has the potential to help users with a wide range of development tasks, including reading, editing, and navigating source code. In particular, users have been shown to spend significantly less time navigating when performing tasks related to understanding code [11]. While the ideals in organizing code in Code Bubbles are similar to a GBPE, it lacks the ability to define distinct relationships throughout the code base.

Incremental Graph Code (IGC) [6] (shown in Figure 1) is our example of a GBPE. This programming environment is built around representing different aspects of a code base in a graph. Nodes capture individual code fragments, documentation, and higher-level constructs (e.g., classes and methods), and edges denote relationships such as execution order, dependencies, and associations between code and documentation.

The initial work of IGC was focused on first creating a prototype that allowed users to create programs in graph-based environment. This work was focused on how to structure, visualize, and interact with code in a graph-based environment. The prototype was built as a full-stack web application with three main views: a file navigator, a graph editor, and a customizable view. Similarly to an IDE, the file navigator allows user to navigate through the code base and open files. The graph editor allows users to edit the graphical representation of the code base while defining various new nodes and relationships. The customizable view would allow users to have a representation of specific aspect of the graph. For example, if a “code fragment” node is selected, the customizable view would show an editor to manipulate and execute the corresponding code.

Although currently IGC only supports Python, the underlying graph structure is not language-specific. A future update will introduce a language manager that will allow users to define and interact with different programming languages. It is important to note that IGC is not a programming language itself, but rather an environment to create and execute code in a graph-based manner. In the same way computational notebooks are not a programming language, but rather an environment to create and execute code in a incremental manner. Similarly to Jupyter computational notebooks, IGC’s graph structure is defined by a JSON-formatted file containing a list of all the nodes and edges. This file is then used to create the graph structure in the environment.

A key focus throughout the development of IGC was ensuring it was extensible. A user can add new node types, relationships, and views without modifying the core codebase. This extensibility is achieved through an add-on manager that automatically detects and integrates new components that can be used in the environment’s user interface. Allowing users to create new node types and relationships enables them to tailor the environment to their specific needs for whatever use case they are working on.

The functionality explored in the initial work of IGC was focused on realizing incremental programming features in the graph-based environment and comparing this to a computational notebook. The work showed that the graph-based environment could be used to create and execute code in a similar manner to a computational notebook, but while also making the structure and interdependencies of large-scale projects explicit, as seen in traditional IDEs. To handle the execution throughout the graph, each execution path is tracked through what we define as a session, allowing programmers to branch off or revisit earlier states and compare different outcomes. All session start at at null state represented by the start node. A “session manager” is just below the file navigator to allow users to manipulate and get an overview of the current session. Although the previous work does not exhaustively define the concepts of exploratory programming or complexity management, IGC demonstrates that a unified, graph-based representation can potentially support both rapid experimentation and effective handling of complex software systems within a single, extensible environment.

In 1983, Beau Shiel, a manager at Xerox’s AI Systems, popularized the term “Exploratory Programming” to describe the challenges of applying rigid software development lifecycles to experimental AI code [36]. In open-ended tasks, where a program’s behavior cannot be fully defined in advance, exploratory programming is a great practice to actively experiment with various code possibilities and discover workable solutions along the way [4]. The style of exploratory programming involves experimenting with different versions of the same code fragment and responding to the observed effects (e.g. modifying and executing a code cell in a notebook multiple times). Various approaches have been investigated to better support exploratory programming in Notebooks [23] or programming environments in general [38].

One approach to supporting exploratory programming is to allow developers to manipulate execution paths to explore and understand alternative branches of program evolution. This approach enables developers to test different scenarios by altering the sequence of code execution. Instead of modifying and executing one specific cell, a developer might also choose to execute an alternative cell to observe how the two compare based on their outputs. This flexibility facilitates deeper insights into how various parts of the code interact. Ideally, outputs from these different execution paths can be easily compared, providing clear and immediate feedback on how changes impact the code’s behavior [29].

In “A Generic Back-End for Exploratory Programming” [16], a generic approach for supporting exploratory programming in programming environments is suggested in which an execution graph keeps track of previously visited program states to which the programmer can return, similar to the record-keeping required for omniscient debugging [9].

Complexity can be defined in many different ways in the scope of software engineering. Most software metrics define complexity specific to a project including number of statements, McCabe’s cyclomatic number [27], Halstead’s programming effort [19], and the knot measure [41, 40]. This project is focused on a programming environment instead of any specific project, so we will focus on how to manage complexity in a general sense. When we refer to complexity, we will be referring to the complexity of the code structure and how it is managed in the programming environment.

For structural complexity, we will be relating to the complexity model of object-oriented systems [37], specifically when it comes to encapsulation, and the reduction of cognitive load by simplifying the interface [30, 15]. Ejiogu refers to this type of structural complexity as “structuredness” [14].

The management of the system through analysis and visualization tools will be another aspect of complexity management. The goal of software visualization is to provide knowledge of a system, program artifacts, and understanding of their relationships [31]. By limiting the data needed to analyze software, we can therefore reduce the complexity of the data shown [33].

This case study examines PescaJ [25], a projectional editor for Java that aggregates scattered code and documentation into unified views. By allowing developers to look at a program from multiple perspectives, PescaJ addresses the complexity of large software systems where navigating interdependencies and associated documentation can be challenging [21]. This approach helps developers mitigate cognitive load by consolidating related information, a benefit especially noticeable when debugging or familiarizing oneself with unfamiliar code [35].

PescaJ departs from linear text-based editors by storing code in a representation distinct from the displayed views. Users can create customizable workspaces to juxtapose both methods and their Javadoc across multiple classes, enabling a higher-level understanding of the system structure. Code views, for example, place dependent methods side by side, while documentation views aggregate scattered comments. The combination helps maintain synchronization between code and its documentation, boosting productivity and comprehension.

In a traditional IDE, a developer might jump between files to update interdependent methods and their documentation. By contrast, PescaJ consolidates these elements in a single workspace. When a method call is selected, the corresponding method’s code and documentation are displayed alongside, reducing the need for tedious navigation. This workspace approach makes it easier for teams to ensure that documentation stays in sync with the code it describes.

In IGC, code and documentation nodes appear within a graph-based interface rather than a projectional editor. When a documentation node is attached to a node containing code, it appears above the code, thus providing a direct correlation between fragments and their respective documentation. Beyond this, users can toggle different projection modes – such as showing only code, only documentation, or both – mirroring much of the functionality found in PescaJ (see Figure 2). IGC’s interface depends on explicit relationships to represent method calls and dependencies, potentially allowing for broader or more detailed relationship views. Currently, there are three different projection categories that a user can select in the projection view: Class, Dependency, and Execution. The class projection view aggregates all code and documentation belonging to a specific class structure (specific to object-oriented languages). The dependency projection view displays code and documentation for nodes along a dependency chain (paths leading from nodes containing variable definitions to nodes that depend on these variables) of a selected variable. The execution projection view displays code and documentation of the entire execution path (if the execution goes through the selected node). The execution projection is a great way to have a similar look and feel to a classic computational notebook.

Both environments aim to resolve the problem of dispersed code and documentation, but they differ in execution. PescaJ creates overlapping, projectional views within a workspace, letting users edit code and documentation side by side. By contrast, IGC employs a graph-based approach that explicitly depicts projections through various relationships. PescaJ’s automatic extraction of Javadoc comments enhances workflow, while IGC necessitates manual attachment of documentation nodes. On the flip side, IGC’s open-ended projections can showcase connections outside the scope of traditional call hierarchies, offering more flexible navigational paths.

As software systems grow in size, developers often rely on modular architectures to cope with increasing complexity [1]. Traditional tools, such as UML diagrams [7], offer high-level architecture designs; however, these designs can become disconnected from actual code, leading to inconsistencies [13]. Model-View-Controller (MVC) is a well-known architecture pattern [34]. The benefits of organizing software according to this pattern hinge on being able to visualize and manage the relationships among components effectively [28].

This case study shows how IGC’s Graph Nodes can be used to encapsulate the model, view, and controller subsystems of a larger MVC architecture. To illustrate, developers can create Model.igc, View.igc, and Controller.igc files, each containing their own nodes and sessions. Once each of the files has been populated with nodes and sessions, a main file (MVC.igc) can then reference these files through Graph Nodes, tying them together with edges that represent interactions among the three MVC layers. This is shown in Figure 3. Since each Graph Node is directly linked to a session, executing the main graph will use the execution order defined by these sessions and run the entire system in a coordinated fashion, enabling developers to observe the application’s behavior without juggling multiple disconnected projects.

Because Graph Nodes encapsulate both the code and its runtime data, the resulting main graph can be viewed and interacted with as a living diagram. Developers may step into each Graph Node to inspect or modify the underlying subsystem. This dynamic representation has parallels to UML diagrams while retaining an executable link to the actual codebase, thus mitigating the risk of architectural drift [13].

Allowing developers to choose a given session for each Graph Node also supports the creation of multiple configurations, facilitating the comparison of different architectural choices. For example, in a typical MVC architecture, you have separate views that interact with separate models via specific controller functions. For this setup, you could have specific sessions for each view, model, and controller.

Where UML offers a static snapshot [7], IGC’s graph-based approach provides a constantly updated depiction of the architecture. From the opposite side of this synchronization issue, model-driven development (MDD) aims to generate code from models directly [12]. However, the production of automated MDD tools is difficult because the semantics carries the meaning that is essential to enable automation for programs [18]. IGC merges the notion of a “model” directly with the code itself. By storing and running code in graph form, IGC sidesteps the friction of maintaining parallel models and codebases, enabling a more seamless architectural view that is less prone to manual synchronization errors.

This final case study centers on an environment that supports exploratory programming by enabling seamless alteration of execution paths. The paper, “A Language-Parametric Approach to Exploratory Programming Environments” [38], discusses an experimental computational Notebook front-end in Section 6 (shown in Figure 5). For simplicity, we will refer to this as the Exploratory Programming GUI (XP-GUI). Traditional edit-compile-run cycles and limited feedback mechanisms often make such free-form exploration difficult, prompting research into specialized GUIs that visualize and compare multiple execution traces (as shown in Figure 5).

XP-GUI offers a tree-based record of execution states (traces), where each node corresponds to a distinct code configuration. However, one branch is visible at a time. Users can branch and merge these execution paths, allowing them to explore divergent scenarios without discarding previous work. Code fragments are run incrementally, with immediate feedback on runtime behavior. An interactive state management system highlights outputs and state changes, and the addition of undo/redo functionality provides flexibility for rapid iterative refinement. These combined features cater to rapid experimentation and serve data science, education, and rapid prototyping scenarios [23, 32].

A typical workflow in XP-GUI has the developer writing code in a notebook-like interface. Executing a cell updates the central execution trace. New branches can be started from any prior state, preserving the original path. Multiple trace endpoints, or “head” nodes, can be marked and compared side by side for deeper insight into the impact of code changes. The system also supports importing and exporting traces for collaboration and reproducibility.

IGC incorporates exploratory programming through the session manager and the Exploratory Programming View (shown in Figure 6(b)), which tracks discrete execution paths (sessions). The Session Manager allows the user to toggle between the sessions to compare execution data. Each session is represented as a node sequence branching from an initial start node, with overlaps indicating shared prefixes. Users can initiate new sessions at any node, insert new code before or after existing steps, or replace code entirely to explore alternative implementations. Although no explicit undo/redo, this functionality can be mimicked by creating sub-sessions derived from another session which provides a new execution workspace to experiment with. A user can always recompute a session if needed by clicking the play button above the graph editor. This session-based approach directly addresses the need for iterative experimentation, allowing multiple development strategies to coexist without losing prior progress.

Although both systems support exploratory practices, they diverge in interface design and code organization. Primarily, IGC visualizes the various execution paths as a tree structure whilst retaining the ability to show notebook-like views through projections. In contrast, XP-GUI requires the user to have an internal mental execution tree representation of the underlying execution paths whilst navigating the different traces and using the trace comparison view. IGC also has more control over the execution paths with actions directly embedded in the exploratory programming view, such as complex branching and re-execution.

Both these environments allow for experimentation within the code base, but IGC’s graph-based approach provides a more flexible and visual representation of the execution paths. IGC is still limited by the need to manually create and manage changes in nodes, often leading to nodes having different versions of very similar code. A proactive model that allows users to define versions of the same node could help mitigate this issue.