Part 1: The Art of Refactoring Spaghetti Code

Jane walked into the conference room for our scheduled skip-level 1:1 and looked baffled. She pulled up the chair and collapsed in it as if she had failed. Jane was a relatively new member of my group who wasn't her usual cheerful self. So I enquired, "How goes it?"

"I cannot fathom!" she exclaimed.

Rolling her eyes in disbelief, she pondered "How did we let our codebase atrophy so badly?"

Sensing her distraught state, I offered a change of plan instead, "Would you like to go for a walk to the lake as we talk today?"

"Sure, why not!", she quipped.

As we walked down the office staircase towards Lake Union, we came across some flowering plants that were in spring blossom. I pointed to them and asked, "Have you wondered how these plants always come out so picture perfect?"

"Yeah, they do look so pretty and well-maintained. I guess, the gardener?", she wondered.

I elaborated, "Yes! Gardening could either be an engaging activity or a chore and it depends on one's perspective. Same is true of software; to own something starts with accepting it in its fullest. Irrespective of whether it is self-written, co-written or inherited, whether it is well-kept or disorganized, whether it is performant or tardy, it all starts with accepting the status quo. I have come to realize that letting go of the need to emote about its state enables me to envision what's next."

"Hmm fine, it is what it is!", she played along.

"Software engineers, especially junior or mid-level will rush to build something new and launch rather than work with what exists. They find it difficult to wrap their head around previously built systems and make a meaningful impact quickly. I know this because I was one of them, early in my career.", I confessed.

She looked puzzled and enquired, "So, what changed?"

"Reflection", I exclaimed as I elaborated, "Let's say you wrote some new code today for an application that you wanted to develop. As you end the day, your first user-story works perfectly; Bravo! Now, let's say you came tomorrow morning to implement a few more user-stories. As you implement them, you realize a common data abstraction across these user-stories is inaccurate. At this point, you would make incremental changes and break your first user-story. However, you will be able to unravel out of this broken state by making compensating changes and making it functional. Correct?"

"Yes, that makes sense", she chimed in.

"Now, let's take an application that you wrote a year ago or maybe more that was probably written by someone else. If you were to make changes in one of these applications and broke some user-story, would you be able to make compensating changes with similar ease or velocity?"

"No way!", she proclaimed.

"Well, what's the difference then?", I asked.

"I don't know. One set of code lines are fresher in my mind than the other?!", she muttered.

I smiled and said, "Yes. And humans have an exponentially decaying memory when it comes to code."

I continued, "So, we need a safety-net to enable building our mental models or reinforcing them when aspects of our mental models have decayed. This safety-net manifests in various forms - unit tests, integration tests, functional tests, canaries, design documents, API documentation, demo recordings, run-books, dashboards and such. Now let's look at these scenarios from a different dimension. What is the commonality amongst them?"

"Well, they both are changing lines of code", she stated simply.

As we headed back to our desk, I countered, "Exactly! So our profession's second truism is that everything tends to change - code, user-stories, dependent libraries, customers and sometimes even our team members too. Change is the only constant as they say. Whether one works on greenfield code authored today or brownfield code from a year ago developed by a peer or legacy code from ten years ago, the only constant is change. Boiling this down to simple principles, first, we should always be building safety-nets and second, we should always be ready for change, in software-speak, refactoring."

"That's insightful! But our codebase doesn't have any tests and has very lean documentation. How do I deal with the spaghetti code and make it better?", she enquired.

I posed a counter-question, "Have you read Martin Fowler's book on 'Refactoring'?"

"Nope", she responded.

"Well then, why don't you read the first chapter and we can discuss this further?"

Next day, as I came out of our monthly demo meeting, Jane called out, "Have a minute?"

"Sure", I responded. She continued, "That book was a really good recommendation! Thank you" she chirped.

"I now know how to tackle our codebase. I am unblocked!", she spoke confidently.

"Glad to be of help!", I smiled and continued, "I have a more elaborate reading list if you are interested."

"Yes, please", she smiled.

---

Part 2: Getting to clarity

---

Disclaimers: All characters and situations are imaginary. Any resemblance with reality is purely coincidental. All opinions are my own and not of my employers.