CodeSee Maps are so much more than just code diagrams. Maps provide developers and teams a means of sharing key information about code—all within the context of the complete codebase.
With features to build customized views of codebases, Maps can be used to guide cross-organization collaboration, drive developer onboarding, improve code reviews, and more. Below, we've shared some of our favorite Maps types, along with some guidance on using Maps Labels, Notes, and Tours to customize your codebase views.
Types of Maps
- Overview Map
- Ownership Map
- Onboarding Map
- Technical Debt Map
- Feature Map
- Explore & Learn Map
- Feature Planning Map
- Pitfalls Map
- Notable Mention: Review Map
Getting Started with Contextual Maps
CodeSee Maps have features customizable for each type of Map created. To get the most out of your Map, we suggest the following sequence:
- Decide on the type of Map you'll be creating—what value do you want it to provide your team?
- Duplicate the auto-generated Map and begin customizing the view based on your use case. Does your use case require you to zoom into an area of the codebase? Would it be helpful to collapse irrelevant files and folders so they don't distract from the knowledge you need to share with teammates?
- Use Labels and Colors to designate and color-code files and folders you would like to group. Be intentional with color choices and keep accessibility in mind.
- Add Notes to add additional context to any file and folder.
- Finally, you can create Tours to offer asynchronous, step-by-step visual walkthroughs of a Map.
An Overview Map shows where different functionalities of a codebase take place, making it a great dedicated resource to reference regularly.
Say you're working on a feature and need to look up how different modules interconnect. Or you want to check if a specific abstraction of a Button component is the correct one? Having an automatically-updating Overview Map lets your developers have a consistent place to come back to for general context.
- Use Labels and Colors to denote different functionality sets, for example, Invoicing, Ordering, Users, Profiles, Admin, etc.
- Remove config files or others not relevant to the functionality areas.
The Onboarding Map can be used to help developers onboard to specific areas of the codebase. How does a particular area of the code work? Depending on how deep they want to go into the codebase, you can decide if one or multiple Onboarding Maps are needed to prepare them to begin contributing.
- Use Tours to display key flows through an application (for example, login or checkout) or critical files or directories based on what you're developing (for example, UI). Try to keep Tour text concise and use Notes to go into detail.
- Label antiquated paths and patterns to replicate.
- Use Colors to show areas of the codebase that would be especially helpful during onboarding—for example, frontend vs. backend, API vs. business logic vs. helpers, languages, etc.
- Create focused views of important areas of the codebase that may require a deep dive.
- Routinely check Insights to see how the codebase is evolving.
An Ownership Map allows the organization to showcase those responsible for various areas of the codebase. It would then be valuable to have a specific Map for each group.
This type of Map shows you who to contact for code-based questions so you can make sure you're addressing bugs and other maintenance matters with the right person on the right team.
- Use Colors and Labels to distinguish owners.
- Mark sub-teams within Maps bounds and folders, then, expand folders to place individual owners using alternative colors.
Technical Debt Map
A Technical Debt Map is helpful for codebase maintenance and project planning, including identifying the scope of work and visualizing potential issues in the code.
- Use Labels to reference the severity or urgency of technical debt. For example, a dim color could be used for low urgency whereas a high urgency area could be distinguished with a bright color.
- Use Labels for the types of technical debt within a codebase. For example, files to break up, etc.
- Use Notes to explain the problem and why it needs to be addressed.
- Use Notes to mark teams that should tackle certain areas of technical debt.
- Map Insights are especially useful to glean additional context in this type of Map.
Use a Feature Map to explain to others how a feature is architected. This Map will appear similar to an Overview Map, except it's targeted at a single feature.
- Collapse files and folders not pertaining to the feature being showcased.
- Add comprehensive Notes to key files to explain functionality in detail.
- Create a Tour to walk through the feature in execution order.
Feature Planning Map
Use a Feature Planning Map when your team is beginning to define their next new feature. These Maps are especially helpful to communicate and discuss proposed architectural changes.
- Hide the nodes on your Map that won’t be affected by the new feature.
- Use Labels and Colors to communicate areas and ideas.
A Pitfalls Map warns less familiar developers of Programming Gotchas and how to avoid them.
- Identify a pitfall, then Label the file. Some Labels to consider adding are "ask an expert," "performance critical", and "easy to cause bugs."
- Add a Note to a file to explain the pitfall and what a developer could do to avoid or mitigate the risk.
Explore & Learn Map (For Personal Onboarding)
Use Explore & Learn Maps during your personal onboarding journey to a new area of the codebase. This Map is a great way to keep track of what you’ve learned as a method of “visual note-taking” as you systematically go through and examine the areas of the codebase you need to understand.
- Collapse nodes that will not be relevant to your work.
- Add Notes to remember what directories contain.
- Create a Tour to demonstrate the order of operations and walk through code flows.
- Use Labels to mark places to ask questions about—then use the Ownership Map to learn who to ask!
- Use Colors to mark areas of interest or potential refactoring.
Notable Mention: Review Map
Our most popular Map across teams is one that requires no additional configuration. Once a CodeSee Map is installed on a repository, a Review Map is automatically generated with every code review.
With Review Maps, contextualize the potential impact of code changes, address feedback, and track the progress of your review—all in one end-to-end experience. Now, with the Review Maps extension for Visual Studio Code, Review Maps are available in your VS Code environment.
- Code is grouped intuitively so that developers can review based on logic and functionality. For example, choose to review left to right (general to more specific) or vice versa and review sections based on type (back-end vs. front-end changes, etc.).
- Double-click on individual files in a Map to view code in a side-by-side diff.
- Place comments to guide contributors, mark files as ‘Viewed’, and even approve reviews—your work will automatically display across GitHub and VS Code.
- Mark sections as 'Reviewed' as you move through a code review.
Start Leveraging Maps for Shared Understanding
With Maps, you're empowered to share your codebase understanding with other developers and teams. Maps are easy to use, and effortlessly fit into existing workflows. And because they're automatically generated and sync to your codebase with each commit, they're efficient and future proof—evolving with your codebase and team.
We can’t wait to see what you build!