Code Compass: A Study on the Challenges of Navigating Unfamiliar Codebases
Ekansh Agrawal, Omair Alam, Chetan Goenka, Medha Iyer, Isabela Moise, Ashish Pandian, Bren Paul
TL;DR
The paper addresses the challenge of program comprehension in unfamiliar codebases and introduces CodeCompass, an IDE-integrated solution that embeds documentation and task guidance within the debugging workflow. Through need-finding and formative studies, it demonstrates that integrating context-aware documentation reduces disruptive context switching and improves task completion. The design, implemented as a TypeScript-based VSCode extension with a sandboxed execution environment and line-by-line explanations, supports multiple learning styles and aims to streamline onboarding to new codebases. The work outlines practical implications for developer productivity and offers a roadmap for automated task generation, broader IDE integration, and pedagogically-grounded evaluation.
Abstract
In our research, we investigate the challenges that software engineers face during program comprehension, particularly when debugging unfamiliar codebases. We propose a novel tool, CodeCompass, to address these issues. Our study highlights a significant gap in current tools and methodologies, especially the difficulty developers encounter in effectively utilizing documentation alongside code exploration. CodeCompass tackles these challenges by seamlessly integrating documentation within the IDE, offering context-aware suggestions and visualizations that streamline the debugging process. Our formative study demonstrates how effectively the tool reduces the time developers spend navigating documentation, thereby enhancing code comprehension and task completion rates. Future work will focus on automating the process of annotating codebases, creating sandbox tasks, and providing dynamic support. These innovations could potentially transform software development practices by improving the accessibility and efficiency of program comprehension tools.