How to pitch a rewrite to a codebase

I once contracted for a company for two weeks in between jobs a few years back. It was a group of people who had bought an application, some kind of internal team loyalty program. Essentially, it was just an internal Facebook with the ability to give kudos to people in a company-wide setting. Ultimately it didn’t do that much, but what it did do, it did pretty well. Now the problem was, and the reason I was bought in, was to add some features. That's fine, I can add some features and at the time the backend was written in Elixir, which is a language that very few people here in Australia have any experience with, I just so happened to have that experience. I said yes to the gig and began setting up the projects on my local machine. To cut a long story short, it took me 3 days to get the frontend working, and some of the packages were so old that they no longer could be downloaded from NPM. The backend was even worse, it hadn’t been touched in years. It took me a solid week to get it up and running and in the end, it still didn’t work quite perfectly.

After this week and a half escapade, I contacted the manager. He was a non-technical person who was supposed to run me through what needed to be done. After the discussion on what needed to be done, I mentioned the sheer difficulty of getting this all up and running and in my opinion what needed to be done before any kind of new features could be added. Ultimately the company rejected my proposal and in turn, I ceased working further with them, because what they were asking was impossible in my professional opinion. 

Although the rewrite never happened, the experience of proposing what needs to be done and why is important. Furthermore, this was an extreme example, however, in your career, you will likely face a similar situation. Perhaps less extreme, but being able to discuss this with your manager is important.

Identifying the problem

The biggest hurdle you will face is identifying the problem. You can’t propose a rewrite simply because the backend is written in Java and you prefer C#. A business doesn’t care if you like the language or not, they only care about making a product that users enjoy and want to use. To even suggest a rewrite, it has to play into this specific goal. In the example from earlier, they wished to add new features to enhance the service they provided their customers. This in turn would bring in more customers. The conflict in this, was that given the current codebase, you couldn’t add anything because you could hardly run the program locally, let alone alter it. This directly affects the company's ability to reach new customers and expand its business. This is a perfect reason for a rewrite.

“We must rewrite the frontend, because the codebase is unmaintained, and lacks any place to fetch critical packages to run the application. Furthermore, there are zero tests, which means if we alter anything we can easily break existing functionality. Ultimately, this codebase is also using a framework that is abandoned, which results in bugs and security vulnerabilities. Because of the state of the codebase, it is next to impossible to add new features. It will cost the company more time and money to add new features now than it would to rebuild from scratch, including adding the new features”. 

This from a developer's perspective are the issues with the codebase that directly affect the business in a technical sense. You must identify the problem and translate that problem into an easily understandable business problem.

“I want to rewrite the backend because it’s written in Java and I don’t like Java, C# is better”. 

To a business, this has no bearing on its profits or their business goals. This is not a problem for the business, simply for you. Java is a perfectly good language you can add new features too, and so is C#.

You must identify the specific business problem with a codebase. If you’re handed a codebase and the framework that it is built off is unmaintained, there are no tests and critical packages are unmaintained or do not exist anymore. These are all reasons to perform a rewrite. Furthermore, if a codebase is extraordinarily complex, in the sense that adding anything breaks everything or even the simplest of features causes a headache. That can also be a sign for a rewrite, although this can be a fine line between a rewrite and gradual improvement. 

You have identified the problem, it's specifically affecting the business and the productivity of the business in reaching its overarching goals. Now what?

Presenting the pitch

Pitching the rewrite is difficult. If your manager is non-technical, or you have to pitch to a non-technical person, this requires a lot more work on your part. It’s easy enough to pitch to a developer and say that this codebase is awful, the packages are unmaintained and building anything on top of it, would be like building a house on quicksand. 

Pitching to a non-technical person is where you must spend careful and deliberate time in preparing the right information. You must convert the technical problems, into business specific terms. It’s of no use to explain that the codebase is bad, you need a valid business reason. Even that the codebase is slow, that it’s difficult to add new features, might not be enough. I have seen a company that had awful codebases, it took increasing amounts of time to add code, yet they wouldn’t spend anytime even addressing the technical debt left behind. Sometimes there is simply no convincing, however, it is up to you to present all the facts that affect the business.

Highlighting as many concerns with the codebase that directly related to how the business makes money. For example, if the effort to add a new feature is taking increasingly more time, then this is a sign that the codebase isn’t in order. If bits of your software is unmaintained, that is a framework or a package that you rely heavily on, this is another sign your codebase is not in order. Ultimately, the pitch is if in your opinion the codebase is unsalvageable, you start again and that in doing so will have greater benefits to the company and it's profits than not doing it.

A rewrite will cost more money than the company wants to spend, because in their eyes, a customer doesn’t care about what the code looks like. Except they do, when it directly affects the performance or the amount of bugs in the program they use. There comes a time when you must address the technical debt, if left too long the codebase becomes impossible to work with. Shifting the mindset of the person in charge to focus on what benefits the customer, which in turn, benefits the company, will help you convince them of a rewrite.

Lastly, you can’t use technical terms, it must all be plain English, with clear reasoning as to why you need to rewrite, because if you can’t justify it technically and non-technically, then you shouldn’t be doing it. Many codebases are salvageable, you just have to carve out the time to do so. Again, this might be a similar pitch but instead of starting again, it's spending time to uplift the most problematic sections.

Picking the right tool

The last part of a rewrite is working out what you are moving too. It’s all well and to say this sucks, we need to start again, but not provide any solutions. You must provide a better solution that the current one. You must be able to give valid reasons why rewriting in this new language, or framework or technique is the way to go and why it benefits the company. Not only will this take considerable time, but there are many avenues to think about. 

If it's a new language, how many people know the language? If it's a new framework, the same thing applies. If it's simply rewriting in the same language, how will it be done better this time to avoid winding up in the same spot as last time. There’s no point performing a rewrite if you end up in the exact same spot. It must be defined the paths that you take, that differ from the previous iteration. What makes this rewrite so special? 

Often it helps to establish better practices. In the current codebase, code reviews are rarely done. There are no tests and the people who wrote the core business logic have left long ago, leaving again no tests, and no documentation. In a rewrite, the focus would be on creating a bed of tests, a certain standard the team must meet; As well as implementing code reviews. Both of these go a long way in improving the codebase, and thus you have identified two points of difference from the old codebase. 

It goes a step further, there is a section of the current codebase that is awful. No one wants to touch it, even looking at it, it breaks, thus no one ever alters it. The problem is, this is core business logic, people need to touch it, so people come up with excuses for the business as to why it shouldn’t change, kicking the can further down the road. In the rewrite, instead of going in guns blazing, as a team, you take the time to plan out this important section. How it might be constructed for reuse and easy maintenance. At this point in the company’s life the business logic is more or less set, when the company just began, it wasn’t. Thus, it becomes much easier to plan how you solve that business problem in a technical sense the second time. 

A rewrite becomes less of picking the right tool but picking the right approach. This can often mean a new tool, but not always. The tools are less important than the approach you take, the guidelines you set and the standards you aim to meet. 

In summary, pitching a rewrite of a codebase is hard, it takes considered thought, valid reasoning and a willing business. You can do it, you just have to follow these steps; 

• Identify what the problems are and how they affect the customer/business 

• Identify if a rewrite is necessary, or simply to pay down the technical debt

• Pitch the rewrite to the business with reasons on why it must be done, the benefits it will bring, and how it will be done better this time. If you can perform all these steps, then it’s out of your hands. 

• If you get the go-ahead, make the most of it, spend the time to plan, to put in place the standards that must be met to produce clean code. 

If you follow these steps, not only will your chances of getting the okay to perform the rewrite go up. You will also get valuable practice in negotiation, in letting your professional opinion be heard. A business pays you to perform in their interests and if in your opinion a discussion must be had about this codebase, then you must raise it. A sign of a true professional is one that doesn’t sit ideally by, but at least attempts to improve the company.