Unravelling the Code Tapestry: Conversations with Code Custodians

  • Friday, Mar 1, 2024
A group of software developers sitting around a table, all are using laptop computers. We are looking down at the table from an angle and can see the backs of two developers, one of whom is wearing headphones. Across the table from them, two other developers are engaged in a conversation about the work they are doing.

The cover image for this post is by Annie Spratt

This is part three 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


Embarking on the expansive journey of comprehending legacy code requires more than just observing its external manifestations. In the second installment of our series, “Unravelling the Code Tapestry: Conversations with Code Custodians,” we delve into the crucial phase of engaging with the developers who hold the keys to the intricate labyrinth of legacy systems.

In the Developer’s Sanctuary

Our initial step involves identifying and connecting with the developers who have a direct hand in crafting and maintaining the code. The emphasis here is on those who possess an intimate familiarity with the intricacies of the system, moving beyond mere team members to individuals with a genuine connection to the codebase.

Effective communication is the cornerstone of this phase. We advise engaging in detailed discussions, ensuring that every nuance, challenge, and triumph tied to the code is brought to the forefront. However, our approach extends beyond a mere exchange of information—it’s a collaborative dialogue where the custodians of the code share their experiences, insights, and, crucially, the “why” behind the code’s evolution.

We discussed the importance of “why” in the previous part in this series.

The Art of Note-Taking

As these insightful conversations unfold, meticulous note-taking becomes our guiding principle. We recommend a methodical approach, capturing every detail, revelation, and idiosyncrasy shared during the discussions. The key here is to balance attentive listening with dedicated note-taking moments. If necessary, politely requesting a moment to document ensures that no valuable information slips through the cracks.

In the realm of note-taking, our mantra is “quantity over precision.” Understanding the vastness of the information being imparted, we encourage capturing more than you think is necessary. The intricacies of legacy code are multifaceted, and a surplus of notes acts as a safeguard against oversight.

Embracing Patience and Collaboration

The process of unravelling legacy code demands patience and collaboration. It is essential to communicate openly with the code custodians, expressing a willingness to extend the conversation across multiple sessions if needed. This not only fosters a psychologically safe environment but also reinforces the commitment to a thorough understanding.

Whether in handwritten or digital form, the notes collected during these dialogues are transcribed into a coherent record. Plain text or markdown-based are preferred in the digital realm, ensuring accessibility and simplicity. Importantly, these transcriptions find a home in the realm of source control, serving as a valuable repository for future reference.

Beyond the Conversations

“Unravelling the Code Tapestry” goes beyond the confines of code – it is a journey into the collective experiences, challenges, and triumphs of those who shepherd the legacy system. As we immerse ourselves in conversations with code custodians, we pave the way for a nuanced understanding that transcends the technical facets, shaping a narrative deeply rooted in collaborative exploration.

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

We'll never share your name with anyone else.
We'll never share your email with anyone else.
Providing a subject can help us deal with your request sooner.
Please be as specific as possible; it will help us to provide a more specific response.
Un-checking this box will ensure that your data is deleted (in line with our privacy policy after we have dealt with your request. Leaving this box checked will auto enrol you into our email communications, which are used for marketing purposes only.