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!
When we read code, we’re using our brains to build a mental model of how the code works. When it’s going well, it’s engaging and fun. But sometimes, for whatever reason, the mental picture is just not coming together. Maybe the code base is huge, or it’s written in a way that’s especially hard to understand. In those situations, a visual map of the code can be really helpful, because it reduces my mental workload by creating the pictures that my mind is struggling to create.
In this post, I’ll present a recipe that you can use to visually navigate any Python library and gain a complete understanding of how it works. To do it, we will be using an open source tool called AppMap for VSCode, which I am helping to create.
The procedure like this:
First, install AppMap from the VSCode marketplace, or use the
Install Extension command inside VSCode. So easy.
Next, find or create a test program that uses the Python package. You can write your own, or you can find one in the project repo, or in the documentation, or you can use a test case from the library test suite. In this example, I’ve written a test program called sshdemo.py.
This step is easy, just follow the two-step installation instructions for appmap-python.
If your example program is a pytest or unittest test case, just run the test case with
If you’ve written an example program, like I’m doing here, run the example program with
appmap.Recording wrapped around it, then print the AppMap file.
An AppMap file will be generated, which is just a JSON file with the extension
Click on the AppMap JSON file. It opens in VS Code as a beautiful diagram! There are two diagrams, actually. Note that at any point, you can click on an object in a diagram to see details in the left hand side panel. From there, you can click “View Source” to open up the Python file corresponding to the diagram object. In this way, you can navigate quickly and easily between packages and code.
The Dependency map shows the high-level picture of the code packages and how they relate to each other.
The Trace view shows the detailed execution path through the code, with parameters, return values, exceptions, etc.
This is just a quick overview of using AppMap to explore and learn a Python package. You can visit appmap-python on GitHub to learn more about topics such as:
Originally posted on Dev.to