When you take a new task on an unfamiliar code base, the process of trying to learn all that code can be daunting. An AppMap is a very helpful tool for learning how new-to-you code works, because:
So, instead of trying to read all the code, you use AppMaps to learn and read just the code that’s relevant to your task. The source code is just a click away, so you can move smoothly back and forth between high-level code design views, code execution traces, and source code details.
To use AppMap to learn unfamiliar code, you’ll need to accomplish the following steps:
Let’s go through this step by step.
First, you’ll need to install the AppMap extension for your code editor. You can find setup instructions on the Quickstart page.
In this guide, we’ll assume that you’ll be obtaining AppMaps from a Wiki, a README/Markdown file, or from a developer who’s already familiar with the code. Therefore, you won’t need to install the AppMap agent or configure the appmap.yml. Just perform Step 1 - Install AppMap for your code editor.
Maybe you’ve already done this, but now you should obtain the project source code. You’ll want the AppMaps and the project source code to be open together in your code editor, so that you can follow links back and forth.
Now you’re ready for some AppMaps. How you obtain these depends on what’s already available and in-place for the project you’re working on.
There are four ways that this can happen:
Depending on what kind of issue you’re trying to solve, you can employ different strategies with AppMaps.
The top-down strategy is recommended when discovering how an unfamiliar code base works. Start with the big picture - the Dependency map - and drill down into individual components and their interdependencies from there.
Instead of starting with the big picture - or in concern with your top-down exploration - you can directly focus on an area of interest.
Understand a new codebase quickly with AppMaps.
I was recently answering a question on StackOverflow when I began to think about the root cause of many of these questions. Someone is trying to integrate a new library into their code, but even after reading documentation and relevant blogs, it’s not clear how to make it work. I’m sure we’ve all been there!