Learn how new-to-you code works


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:

  • AppMap includes more than just code - it also has all the web services, SQL, dependency services, libraries, and security functions, and their interactions with application code
  • The AppMap contains only the code that’s relevant to a particular use case or operation.
  • You can search and navigate the code base at a high level, and quickly drill down to low-level details.
  • The AppMap links to source code, so you can immediately get into the code whenever you want to.

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.

How it works

To use AppMap to learn unfamiliar code, you’ll need to accomplish the following steps:

  1. Install the AppMap extension for your code editor.
  2. Obtain the project source code.
  3. Obtain AppMaps which are relevant to your task.
  4. Open and use AppMaps.

Let’s go through this step by step.

1. Install the AppMap extension for your code editor

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.

2. Obtain the project source code.

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.

3. Obtain AppMaps which are relevant to your task.

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:

  1. The code issue, task, or ticket that you’re working on has an AppMap attached. This is the best-case scenario, because the AppMap is directly relevant to the work that you need to do.
  2. Project developers who are familiar with the code have created a Wiki or README/Markdown files that describe some key elements of the project architecture. AppMaps are attached here, or there are links to AppMaps stored in AppMap Cloud.
  3. No-one has created AppMaps yet, or the AppMaps that are available aren’t suitable for your task. You can ask a project developer to create an AppMap or two for you, based on their knowledge or expertise. These AppMaps can be added to the architecture knowledge base. You can offer to do this! Chances are, this offer will definitely be appreciated and accepted.
  4. There aren’t any AppMaps available, and there isn’t anyone around who can create them for you. In this case, your best bet is to finish the Quickstart guide. Then, if your app has a UI, use Remote recording to make an AppMap as you use the application feature that you’re going to work on. If the app is headless (e.g. an API), you can write a test program or run a test case to capture an AppMap.

4. Open and use AppMaps

Depending on what kind of issue you’re trying to solve, you can employ different strategies with AppMaps.

Top-down approach

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.

  1. Start with the Dependency map, and observe all major components of the application and how they are interrelated.
  2. Inspect web services and their parameters.
  3. Drill down to classes and functions that implement web service handling.
  4. See how code sections interact and how data flows.
  5. Observe dynamic dependencies between internal and external components.
  6. Observe how internal and external components interact with the database.

Bottom-up approach

Instead of starting with the big picture - or in concern with your top-down exploration - you can directly focus on an area of interest.

  1. Choose a SQL query, code label, or function call.
  2. Find the code object by searching in the navigation bar
  3. Open it in the Trace view, see how it is interconnected with downstream and upstream events, and navigate to its caller to see where it is used
  4. Observe the surrounding code in the Trace and dependencies in the Dependency Map.

Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!