Unravelling the Code Tapestry: Why Documentation is Key to Legacy Code Success

The cover image for this post is by Christopher Gower

This is part four in our series of blog posts detailing our system for genius when working safely with legacy code. The other parts of this series include:

1. A Series On Safely Navigating Software’s Timeless Artifacts
2. Preparing To Tame Legacy Code With User-Led Odysseys
3. Conversations with Code Custodians

Introduction

It’s easy to get excited when you take on a new programming challenge, especially if it involves working with legacy code. The allure of uncovering hidden gems and modernizing outdated systems can be intoxicating. But before you dive headfirst into the depths of an unknown codebase, it’s crucial to remember the importance of gaining access to any and all existing documentation for a legacy project.

In our previous posts, we discussed the importance of understanding the context and history of a legacy project, as well as how to navigate its structure and organization. Now, we’ll focus on why it’s so critical to obtain documentation before attempting to look at or run the code itself.

Documentation: The Rosetta Stone of Legacy Code

A well-documented legacy codebase can be your greatest ally when it comes to understanding and working with unfamiliar code. It provides a roadmap for navigating the project, explaining why certain design decisions were made and how various parts of the system interact with one another. Without this context, even the most experienced programmer can easily become lost in the weeds of an unfamiliar codebase.

Unfortunately, not all legacy projects are blessed with comprehensive documentation. In fact, it’s not uncommon for important documentation to be scattered across various file formats, locations, and mediums. This makes it essential to conduct thorough research before beginning any work on a legacy project. Here are some steps you can take to locate and gather relevant documentation:

1. Search the project’s source code repository: The first place to look for documentation is usually the project’s source code repository, such as GitHub or Bitbucket. Look for README files, documentation directories, or markdown files containing notes and comments about the codebase.
2. Check version control history: Reviewing the version control history can reveal old commits that contain valuable information about the codebase, including comments, changes, and even deleted documentation.
3. Interview team members: If you’re part of a larger development team or if the project has been around for a while, there’s a good chance that other team members have insights into the codebase that can be invaluable. Set up interviews with key stakeholders to gather their thoughts and experiences working on the project.
4. Examine related artifacts: Legacy projects often generate a variety of artifacts such as design documents, user manuals, and test cases. These items can provide valuable information about the intentions behind certain code structures and functionality.
5. Research external resources: Don’t limit your search to internal sources; check online forums, blog posts, and documentation portals related to the project or its technology stack. You might be surprised what you find in these corners of the internet.

Once you’ve gathered all relevant documentation, it’s important to review it carefully and organize it in a way that makes sense to you. This will help you understand the codebase more effectively and make it easier to navigate as you begin working on the project.

Dependencies

In addition to the contextual information and organizational structure discussed in previous posts, it is important to gather comprehensive documentation when working with legacy code. Comprehensive documentation should include requirements such as operating system, supporting libraries, external applications, framework and tool versions, as well as steps to get up and running, and information on any linters used, etc. This will help ensure that changes made to the code do not inadvertently break functionality due to compatibility issues or missing dependencies.

It is also important to gather information about package feeds (NuGet, npm, gems, etc.) used by the project and how to access them. You may need to explicitly request access to these feeds if they are private or require authentication. If so, you’ll need to know who to request that access from. Once you have access, ensure you understand the permissions granted and any restrictions that apply.

Being able to access any information on the build pipelines used (such as Azure DevOps or Github actions) is crucial for understanding how the codebase is deployed and maintained. This includes knowledge of continuous integration servers, deployment scripts, and monitoring tools. Understanding this process will help you integrate your changes more seamlessly into the overall development cycle and minimize disruption.

In addition to gathering documentation related to the code itself, it’s important to identify any external resources or online services that the project relies on. This could include APIs, cloud storage platforms, or third-party libraries. You may need credentials or other forms of authentication to access these resources, so make sure you request them early in the process. We discussed this in the previous part of series: Conversations with Code Custodians

If documentation is stored in a company wiki or an external site, make sure you identify these resources and request access if necessary. It’s important to have all the information you need to work safely with legacy code. Once you have access to all relevant documentation, organize it in a way that makes sense to you and familiarize yourself with its contents.

Outdated or Updated?

When working with legacy code, there may be multiple versions of the documentation available. Make sure you understand which version is most up-to-date and accurate for your purposes. If necessary, coordinate with team members or project leads to ensure that you’re using the correct documentation.

It’s also important to keep in mind that documentation can become outdated over time, especially in legacy projects. Be prepared to update or create new documentation as needed to reflect changes in the codebase or development processes. This will help maintain the quality and accuracy of the available information and make it easier for others to work on the project in the future. We will discuss this process in a future post, so keep an eye open for that.

Finally, remember that working safely with legacy code requires patience, careful planning, and a deep understanding of both the technical aspects of the codebase and its context within the larger project. This is why it is crucial to gain as much information ahead of building and running the code as possible; and this can be done by reading through the documentation.

In Conclusion

In conclusion, working safely with legacy code requires a deep understanding of both the technical aspects of the codebase and its context within the larger project. Gaining access to all available documentation before attempting to look at or run the code is critical to ensuring that you’re starting off on the right foot. By following these best practices and approaching your work with caution, you can help maintain the stability and reliability of legacy systems while modernizing them for the future.

Stay tuned for the upcoming chapters as we delve further into the art of deciphering legacy code and navigating the intricacies of software archaeology.

If you’d like us to help you work through the challenges involved with working safely with a legacy codebase, either in a hands-on capacity or as a consultant, get in touch with the form below