CodeSee Function Maps

Service Maps and Flows side by side

The primary feedback that we received for Codebase Maps1 is to be able to visualize functions. This makes sense – when people think of code they are usually imagining a few key functions or areas in a sea of code. To be able to explain or grok something would require the ability to represent them visually.

The problem, or challenge shall I say, of giving shape to functions is the sheer number of them in any given codebase. A typical production Codebase contains hundreds if not thousands of files; the amount of functions in them are easily a magnitude larger, and the lines of code another magnitude or two more.

That’s what we set out to do. Of all the things we made at CodeSee, Function Maps resonated the most with users and customers. Getting there was not easy, and I’ll talk a bit about how we got there.

TL;DR

  • The key challenge in representing functions or code is finding the right level of abstraction that helps with learning and understanding that does not overwhelm the user.
  • Function calls are but one way to represent work done inside of codebases. To capture how people understand codebases, we built ways to bring related code snippets onto the map.
  • Software is always done as a team. To complete the loop, function maps had to gain the ability to annotate and share the knowledge that is produced and captured.

Initial explorations

To begin, we had to understand what visualizing function means. We couldn’t take the naive approach. If we show functions indiscriminately, it would quickly overwhelm a user working with codebases of any modicum bit of complexity.

So what do we know? First of, we know how people use Codebase Maps and the strengths and weaknesses of using file structure to represent knowledge. Secondly, we can consult industry sources. The C4 model has a good breakdown of software diagraming, and says this of the code diagram level, “this level of detail is not recommended for anything but the most important or complex components”.

We also know that when people describe functions as a way of explaining or understanding codebases, they are thinking of the few important chunks of code – be it business logic or architectural cruxes – and discarding the bulk of other code that is written to route, support, or test them. With these in mind, I started building prototypes to explore “showing functions inside visualizations”.

A wireframe prototype showing a map and source code side by side. In the map view, files show functions that are linked to others on the map.
Excerpts from a prototype: this approach layers code and map side by side. The user uses the map to navigate and the code view to highlight and link function.
A wireframe prototype showing a map and source code side by side. In the map view, a snippet of code is displayed and the corresponding code is highlighted in the code view.
Excerpts from a prototype: This prototype uses the code view to do more of the heavy lifting. The assumption here is code is primary and the map is more of a navigational device.
A file is focused on a codebase map that shows functions and relationships. The highlighted function of this file is connected to the definition in a different file.
Excerpts from a prototype: in this prototype, the map serves as a jumping off point to start building relationships.
A codebase map with a search bar on the top right. The search text reveals items that are in the map and controls to toggle their visibility.
Excerpts from a prototype: here, the user uses the search bar to find and toggle function level details in the map.
A codebase map with the file server.ts in focus. The descendent entities are displayed in a list and can be toggled on or off.
Excerpts from a prototype: every file in this prototype, when clicked, shows a list of entity relationships that can be toggled on.
A function call graph and entity relationship tree layered on top of a codebase map.
Excerpts from a prototype: the user can use any file on the map to explore the relationships and call graph.

With these sacrificial concepts in hand, Josh – one of the co-founder – and I came together to interrogate these prototypes. We talked about their strengths and weaknesses and tested them against our original goals and design constraints.After doing the synthesis, we settled on a few key design principles and built more prototypes.

A photo of a whiteboard with boxes and lines representing entity relationships.
Whiteboard sketches of ideas that the prototypes inspired.
A map showing three snippets of code, which are linked together by arrows.
An iteration of the inline design that closely resembles the shipping product. One foundational change here is the idea of building up instead of paring down.
A map with boxes representing files with functions in them, and the selected source code on the right.
Another iteration that has the code displayed on the right in context of the source file.

Validation testing

From the candidate wireframe, we built a prototype demonstrating the key features of Function Maps and how it would work on a real codebase. We then show this to a few software engineers.

The feedback was positive! One participant noted that of all the new product ideas that he has evaluated, this would stood out the most. For software engineers like himself, they often struggle with sharing and explaining their work to other members of the team, especially when the code is gnarly and is difficult to glean from in a short code review. Having a tool that is able to strip out the noise and focus on the key paths can improve productivity for both the author and the reviewer.

The research helped us build an understanding of where this tool may fit within the engineering roles and team workflow to guide the design and development of the product. More importantly, there were a few immediate and tangible next steps to focus on.

A screenshot of Figjam with clusters of sticky notes representing an analysis from user interviews.

Research analysis with takeaways and analysis on where it fits in the user workflow, synthesized from user interviews.

Foundational designs

At it’s heart, Function Maps is about building a flow chart out of snippets of code inside a codebase. The core interaction starts with putting a code snippet into the map, and then clicking on symbols to reveal their implementation and follow them. Over time, this creates a tree that represents important paths that the code may take.

While the design may seem simple, it is definitely not straightforward. Even though the canvas is infinite, we are restricted by the physical screen dimensions in computers. This resulted in a lot of deliberation around the right default density of information and creating correct and useable dials for people to go in and out. In addition, because we are breaking long held expectations around files and tabs, we have to provide suitable alternatives so that people can relate what they are looking at to the environment that they eventually need to work in.

A UI containing three code snippets connected to each other via arrows.
Functions are displayed in nodes, which can then be linked to other nodes. Users can truncate or minimize code so that the relationships are front and center.
A zoomed out view of connected nodes in the Function Maps UI.
When zoomed out, the architecture and relationships inside of the codebase becomes much more apparent. This is superior to the typical approach of juggling tabs.
A context menu when the user clicks on a symbol in the Function Maps UI.
In addition to leveraging built-in code analysis tools, users can create manual relationships to highlight non-obvious dependencies.
A screenshot of a Figma file with different sections and details within them.
An overview of all the parts of the initial design spec for Function Maps.
The modal UI for when the user is manually creating links between symbols in nodes.
This is when the user is creating manual link. This shows how the design has stepped forward, with much more subtle treatment of links and other enhancements.
Multiple nodes are selected with new controls in the toolbar in the Function Maps UI.
When multiple nodes are selected, a selection toolbar appears. Part of creating a visualization tool is giving users manual control over layout.
Two nodes in Function Maps. The left node has an open dropdown that displays a list of function names nested within each other.
Here is a later design for the header. In the node of the left, the dropdown shows the hierarchy that the current code snippet belongs to.

Beyond function calls

The first diversion from the initial plan was to consider how to visualize object relationships on top of function calls. While following function calls is broadly useful, this may not be the best way of looking at a codebase. For object-oriented languages, resolving the full code path often involves traversing up complex inheritance chains.

To represent the fullness of the code paths, we had to rethink the way nodes relate to each other on the map. The result is a map that went beyond function calls. Users can now inspect any class or class method and find a list of code nodes that it may be related to, and add that to the map. This is especially helpful for coding patterns that rely on code reuse.

A dialog with class hierarchy on the left and a source code view on the right inside of the Function Maps UI.
The user can “add related” above any class definition or method to navigate and add the full implementation hierarchy.
A dialog with related symbols grouped by files on the left and a source code view on the right inside of the Function Maps UI.
Function Maps also exposes symbols that are located in the same file and folder as the originating symbol.
A screenshot of a set of design explorations for the dialog in Figma.
There was extensive explorations on how to represent all these various relationships in a way that is easy to understand and make decisions upon.
Three code nodes with one of them showing a highlight on the left and the merge action above inside the Function Maps UI.
In large maps, functions often link to each other. When there are repeated code snippets on the map, we highlight them and provide a way for users to merge the nodes together.

Annotations and sharing

While the visualization helps with learning or expressing source code, it is only half of the problem. Since most users work in teams, the next most useful thing for them to do is to add annotations to the map and then share the map on a communication tool or documentation site. Here are a series of designs for that.

Function Maps with a bottom toolbar. The Notes item is selected, there is a color picker, and there is a semi opaque note following the cursor.
Unlike most developer tools, Function Maps is first and foremost a canvas. We wanted the design to mimic a physical surface that feels real and tangible. This design never shipped.
A note inside the Function Maps UI that is being edited.
The user can add notes to the map. These notes are independent just like code nodes, and can be edited, linked to, and moved around.
A flow diagram showing the transition between the various states of the Note node.
We have to take care of how mouse and keyboard interactions intersect on the canvas.
Function Maps UI with the sharing dialog open.
We decided on a publish model for sharing. This helps reduce implementation complexity while providing control over when and where source code is shared.

Release

Function Maps launched on the Visual Studio Code marketplace on October 2023. It has a one week free trial and was available only to CodeSee Enterprise customers.

Here is a video walkthrough of some of the features in the latest version.

A walkthrough of the shipped VS Code extension.

Reception and aftermath

Function Maps quickly became the main selling point of the CodeSee suite. Prospects were most interested in Function Maps and wanted to see how it would perform in their codebase, language, and framework. A lot of immediate engineering work was to diversify the language support. People started asking for Function Maps in platforms other than VS Code. .

Here are a collection of positive reviews:

[…] the thing itself is almost perfect. It amazes me that this is not a standard feature of vs code, saves so much head space!

This tool is a game-changer. Nothing less. […]

Unfortunately due to a funding gap, CodeSee shuttered their doors on February 2024.

  1. In Codebase Maps, source code was visualized at the granularity of files and folders. ↩

Company

CodeSee was founded in 2019 to develop the world’s first solution for continuous understanding of codebases. The company is based out of San Francisco and is backed by boldstart ventures, Uncork Capital, Wellington Access Ventures, Menlo Ventures, Precursor Ventures and Salesforce Ventures, among others.

Timeline

2023-2024

Tags
  • Product design
  • Information architecture
  • Visual design