Architecture & DesignRe-engineering Legacy Software: Deciding the Project Scope

Re-engineering Legacy Software: Deciding the Project Scope content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

By Chris Birchall

This article was excerpted from the book Re-engineering Legacy Software.

The most important thing to do before embarking on a major software project is to make your goals clear. What do you want to achieve by rewriting the software? And, perhaps more importantly, what don’t you plan to do as part of this project?

What is the project goal?

A rewrite usually takes one of three forms.

  • In a black-box rewrite, the goal is to keep the software’s functionality exactly as it is now, but the internals are re-implemented from scratch. This may be to port the software to a new technology stack (if, for example, it is currently running on a mainframe that is due to be decommissioned), or simply to make the software easier to maintain in the future. In the ideal case, the end user does not notice that anything has changed.
  • In a brush-up rewrite, an additional goal is to use the rewrite as an opportunity to document, update and normalize the specification, so that the new software functions differently (hopefully better!) than the old one.
  • In a quid pro quo rewrite, the goal is to develop some major new features as part of the rewrite project, in order to convince business stakeholders to green-light it. If it were up to developers, we would merrily spend all our working time refactoring and rewriting things just for the sake of it, but the people who pay our salaries need to be given some incentive to let us spend weeks or months rebuilding something that already works.

Imagine that you maintain World of RuneQuest, an online fantasy RPG. It’s a Java servlet application that’s been running for over 10 years. Its technology stack has hardly changed in that time, and it’s become very difficult to work with. The UI is also starting to show its age. The developers are desperate to rewrite the application using modern technologies.

The Product Managers are also on-board for a rewrite, as it will give them a chance to write a proper specification, a vast improvement on the current situation of “the implementation is the spec”. However, upper management is loathe to assign resources to a project that they see as being “by the developers, for the developers,” unless it also provides some benefit to the players of World of RuneQuest.

In this case, it seems like a quid pro quo rewrite is the way to go. Perhaps they could brand the rewrite as a major new version of the game, and they could use the new technology stack to add some new features that have hitherto been impossible to implement. These features, such as in-game audio chat and more sophisticated player stats, are often requested by players and are already offered by World of RuneQuest’s competitors.

Making it clear to the end users that the game is being rewritten also frees the developers from any obligation to perfectly emulate the legacy UI and gameplay, although they will certainly need to be careful to preserve certain core features of the game, to avoid risking a backlash from players.



Adding new features in a rewrite

The idea of adding new features at the same time as re-implementing an existing piece of software, as is done in a quid pro quo rewrite, may be quite undesirable from a developer’s perspective. The conflation of multiple concerns, namely maintaining the original behavior whilst also adding new functionality, may make the project planning more difficult and the resulting software harder to reason about.

However, sometimes adding new features is the only way to provide the rewrite project wih enough business value to get approval. And besides, isn’t building new functionality more satisfying than merely implementing something that works exactly the same as what you already had?


Documenting the project scope

Once you’ve decided what kind of rewrite you’re going to do, it’s vital that you clearly document this fact, along with any other salient details about the scope of the project. The document should be short enough for all stakeholders to read, understand and agree to, but also clear and detailed enough to be unambiguous. This document will be very valuable as a reference when feature creep starts to set in a few months down the line, so it should be written and agreed to with that in mind. Everybody involved in the project should understand that this document will become the Single Source of Truth, so if they disagree with any part of it they should speak now or forever hold their peace.

I recommend including the following information in the project scope document:

  • New features. Are you going to add any? If so, list them. For each one, say whether it is must-have (i.e., the new software cannot be released until it is completed) or nice-to-have (i.e., it could be added after the first release).
  • Existing features. Are there any features of the existing software that you are planning to remove? Are there any particular features that are must-have or nice-to-have?
  • Timeliness versus feature-completeness. Are you more interested in releasing something by a certain date or in releasing a product with all the planned features?
  • Phased releases. Are you planning to make multiple releases, adding more functionality in each release? If so, give a brief summary of the content of each phase.

The final point is quite important. If possible, I highly recommend taking an iterative approach whereby you make a number of small releases, adding more functionality in each release. This is less risky than the alternative, an all-or-nothing Big Bang release at the end of the project, as it gives you the opportunity to get feedback from your users about the new software while you still have time to alter the project’s direction. It also highlights any technical issues with the new software at an early stage, when you still have the time to fix them.

For an incremental rewrite to work, you will need to run the old and new software side-by-side until the new software is complete. This can present some technical challenges, especially if the old and new software will need to communicate with each other. But in my opinion the effort is justified by the the reduction of risk that comes from being able to release incrementally.

Figure 1 shows what a scope document for a rewrite of World of RuneQuest might look like.

Figure 1: An example of a scope document for a rewrite of World of RuneQuest


Re-engineering legacy software: Deciding the project scope

By Chris Birchall

This article was excerpted from the book Re-engineering Legacy Software.

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Latest Posts

Related Stories