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:
- A Series On Safely Navigating Software’s Timeless Artifacts
- Preparing To Tame Legacy Code With User-Led Odysseys
Introduction
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