Clients frequently request that we use existing applications as the basis for work when we are rebuilding or recreating a system with them.
This is very difficult. It can work, but it is much less effective for developers and results in a lot of iterations as the dev team goes back and forth figuring out what an application needs to do. It leads to a lot of bugs that are only discovered in UAT.
In the beginning it is much more efficient for your business stakeholders, which is why they ask for it. Why go through the existing application and document it? That's a lot of work for users and business people, not to mention the BAs you have to pay to do it.
In the end, the same people who didn't want to go through the process of documenting will be mad because it is taking so long. It is your responsibility as a developer, lead, or PM to set the right expectations in the beginning.
If your stakeholder (whether client, boss, CEO, etc.) requires you to work this way you need to expose the risk and set appropriate expectations. The very best case scenario is that you have to set aside time for late project iterations when you run into these challenges. The worst case scenario is that the project will drag on so long that will be cancelled. It happens all the time. Also possible: you fixed-bid the project and put your company out of business trying to complete it.
Setting the right expectations can be difficult, and that is a topic for another post some time. My goal today is just to describe a few of the ways this has come up over the years, so you know what to look out for.
Just make the new app do what the old one does. Why do you need requirements? An all-time classic. Why not? I mean there's already code, how hard can be to just: read it, understand it, understand all the subcomponents and UI, assess whether or not it is still necessary, talk to users, and figure out how to test it. It definitely wouldn't be easier to have that done and approved before you start development. Danger level: Red Flag
Preserve the business logic, everything else you can get rid of. This assumes that preserving the business logic is easy, which it usually isn't. Even when someone has done a good job of separating business logic from UI and data access (very rare) often the technical and business requirements of the rebuild make reusing the code in its original form impossible. Danger level: Yellow Flag
We'll figure it out as we go along. This one can seem reassuring in that your stakeholder has seemingly granted you permission to iterate. But be careful here: set expectations, ask follow-up questions, establish what 'figuring it out' will really look like. Danger level: Yellow Flag
There's a lot you can re-use. Just tell me what it will cost to rewrite the things that you can't re-use when it comes up. You should assume that you are rewriting everything. If you get to re-use something that's a win. It will most likely save you a little time in testing, but not anywhere else. Danger level: Yellow Flag
You don't need to talk to users. Bob knows everything about this application and Bob is your main point of contact. Unless Bob is the only user (and even then) he almost certainly doesn't know everything. Even if Bob isn't an ego-maniac (and he might be) you are still facing delays in understanding the system because Bob has to go ask someone instead of you asking them. Danger level: Red Flag
This spreadsheet will tell you everything that you need to know about the system. AKA Our old system was a spreadsheet, just look at that. Usually these are worse than looking at code because in addition to code (like VBA) you also get things like embedded charts, formulas in cells, and obsure data access thrown into the mix, requiring even more detailed reading to understand. Danger level: Red Flag
Jennifer developed most of the original system and she'll be working closely with you on this project. Usually Jennifer is retiring, and that is a hard deadline. Also, what does most mean? Danger level: Red Flag
We have all the requirements from 20 years of work we did on the old system. You can read through that. To paraphrase Sartre, Hell is other people's requirements documents There are a few reasons why this is true, but probably the most profound is that writing the requirements document immerses the team members in the system. Without having written it, asked the questions, and fully digested the material then you or your BA will always be at a deep disadvantage. I wish this weren't true, but it is. At least 50% of the reason for documenting stuff is to make sure the person responsible really understands it. Danger level: Red Flag
More reasons why code is harder to read than write:
Code is meant to be executed by machines, not to be read by people. In other words, you, as a human, are not the intended audience. Everything about the program you're trying to read, including the intent of the language designers, was focused on machines and not on you.
Developers don't get paid to write, they get paid to build.
Developers prefer to build things over writing about it or adding comments to code.
There is always a deadline. The deadline is never about writing comments or documentation.
I've posted this article recently, but it got me thinking about why code is harder to read than to write. So, I will post it again, to make your life easier and explain why I think that code is still harder to read than write, even all these years later. Here's the article:
The title of this post seems counter-intuitive because we think of reading and writing in relationship to human language, but programming languages are not like human language.
What are the important differences? Here is the main one:
Programming languages can't be read aloud.
So when we talk about 'reading code' we're using 'reading' in a purely metaphorical sense. When you 'read' code you don't actually read it - you're looking at it and trying to make sense of what it does.
This is nothing like reading a book, paragraph, or sentence written in human language.
When you review code you study, you re-read, you look things up. You jump around from file to file. You may consult web pages. Even in programming languages you are familiar with and with a business domain you know, these tasks can be time consuming.
You're trying to 'read' something that can't be read, across many files, and trying to ascertain the author's intent not just comprehend a sentence.
An equivalent would be trying to read in a language where you had to look up every third word, every time you read something because:
Every author used the language in a novel way. AND
Every page of a book was put in a different file and they were constantly referencing each other and not in order.
It would be hard. And it would not really be reading. That's what 'reading' code is.
I reference it again, because it is great and it makes a lot of good points.
One thing it says is that 'Code Doesn't Age'. Specifically, Joel says this:
The idea that new code is better than old is patently absurd.
This is true in many senses: code doesn't get rusty, code doesn't wear out after the millionth time it's used, and you can make a thousand copies and this does not effect the code's quality in any way. Also, as he says, old code has been tested, where new code has not.
However, code can age, and I want to talk a bit about that and what it means to you. How can this ageless thing age? Here's how:
Code Doesn't Stand Alone - unless you have a very, very simple program, it is connected to lots of libraries and (today) APIs. These things don't stay the same, nor are they supported forever. So, your code doesn't physically get old, but sometimes the things that it relies on break, or they get changed, or they are killed off. When this happens, your code just got old, very fast.
Code Runs on Something - it used to be hardware, and deep inside of a data center somewhere that is still true. But even when we're only talking about VMs, VMs have operating systems and supporting code and those things aren't supported forever either.
Code is Written by People - and people don't write COBOL anymore. Or at least most people don't. People also don't write VB or C++ as much as they used to. Sometimes perfectly good technologies fall out of favor and everyone learns something new making your product hard to support.
It used to be, most of what I'm describing happened over a long period of time. COBOL didn't go away overnight, that took decades. But with things being more and more interconnected via APIs, and with more changes coming quickly to platforms and other programs, the pace of change is increasing.
APIs change all the time, which is great (Hooray for new features and better performance!) and also challenging (I have to make the changes by when?).
Sometimes things come and go quickly or you make a bad choice. Silverlight anyone?
So, code doesn't physically age, but it is dependent on things around it. Those things can change or break. If that happens, the code has to be kept up or it has to be refactored or (sometimes) you need to rewrite an application entirely because the people who built the original are all retired.
The good news - you get to build something great with new technology that leverages all the awesome things your old project did, but is new and shiny and fun to code.
The bad news - all the things in that article are still true. So, you need to plan for them.
We're currently having some discussion about what to call this process (Rewrite? Rebuild? Re-engineer?) On the new Exadel website. I'm partial to Rebuild, but I think that Re-engineer is likely to win.
In my relentless pursuit of information on this topic, I'm compiling a list of articles related to it.