The Joel on Software Discussion Group (CLOSED)

I just got given a 200K line windows ( mostly MFC ) application which NEARLY works, that they would like out of the door quickly.
Unfortunately the designer left without any hand over or documentation and it's been sitting around neglected.

I just about got the source to build, but understanding it enough to fix it is going to take time.

Are there any books with advice about this situation - or do all books assume you are starting a fresh project, free to choose the best language / design patterns / platform and with all the requirements gathered !

Don't know about books, but I would start by building a call tree, and pray for loose coupling. The call tree will give you an overview as to the relationships between the bits (functions/source files etc).

You say you're short of time so you may not be able to nail the interfaces in time, which should be the second step. This will give detail on the relationships.

Once you understand how the bits hang together you can happily concentrate on one bit at a time. 200K lines is a lot, so good luck.

As you don't have much time, my recommendation is as follows:
1) Let management know of the situation you are in, and get clear instructions on what they want the app to do before the due date. They should be made aware that due to this situation, it may be wiser to delay some features util a future release.
2) There must be other people aware of the application who can assist. Even testers and support people must be available for some help on the side, and should know enough to help get things moving.
3) Quickly identify the things that don't work, and get some broad ideas of how to fix them. Forget the rest of the application (assuming that you have been told it works as expected), and focus purely on the stuff that does not fully work. From here on it's quick fixes and hacks, but noting these are such and the need to refactor in the future. Unfortunately there is no other way apart from hacks if you don't have the time to work on this at your liesure.

You can try using "Understand for C++" to build a source tree.

Of course "they" said they would like it out the door quickly. What else would they say? "We don't care if this ever gets released"?

The first thing you must know is: What are "their" expectations?

Let's assume they want you to fix this thing properly. In that case, your first order of business is to learn enough to be able to tell "them" whats busted and how long it will take to fix it. Put trying to actually get this thing to work out of your head for the moment. You need to be able to give them a value-cost decision.

Go into learn mode. Talk to anyone who is still around that had anything to do with this thing. What were the initial requirements? What were the issues? etc, etc.

Work to get a 10k foot picture quickly, then refine as needed. Have regular meetings with "them" to inform them of your progress and difficulties. Show them your refined plan and get confirmation that your doing what they want.

Obviously, getting it to compile is a necessary first step, but I urge you not to just jump right in trying to fix things.

There is nothing worse than getting a project that is "alomst done" with expectation if just finishing up the lose ends.

As for books I don't think there is much that can help, maybe Diomidis Spinellis' "Code Reading" but I doubt.

Here are my suggestions:

1.  Make sure you have the build and deployment process down pat before you do anything else.
2.  Be fanatical about your use of source control.  You will need to do some expirementation and rolling back will be important at times.
3.  Probably just as if not more important as understanding the code is understanding the requiremnts.
4.  Set expectations early.  You have been assigned a difficult task and make sure the project owners understand not to expect a miracle.
5.  The best tactic when going through the code is start with small bites of the low hanging fruit and get a complete understanding.  Eventually you'll start to get a picture of how the old developers think or in the worst case don't.

It sounds as though the book that would be most helpful to you in this situation is "Death March" by Edward Yourdon.

The book is about all those projects that you know can't go well, but which, if you do the right things, you might possibly survive.

Thanks - I saw "code reading" but it's C/Unix kernel based. The book I remembered was more windows - it covered source tree and call graph analysers with MFC.

The main problem is that the app looks finished, all the pretty graphics are there, it just produces weird error messges, occaisonal lockups and sometimes the wrong answers. ( this is a medical imaging app - so not good ! )

I'm new to the group and don't have a feel yet for wether I am the hero for rescuing this product or am going to be blamed if it's not released in a week !

One of the very basic principles of software development is the ability to treat objects, methods, and abstractions as "black boxes" that just work- you put your input in the front and you get the expected output from the back.  This concept is what makes large software development possible, but for that to work you have to be able to not only identify black boxes but have a certain level of trust that they will work as advertised.  In your position the former will be difficult but ultimately possible.  The later is going to be a real problem.  "Good luck" is all I can say.

"... it just produces weird error messges, occaisonal lockups and sometimes the wrong answers."

The word "just" almost certainly does not belong anywhere in that sentence :-)

I know you're trying to do this on Windows, but if you have the time and inclination to acquire them, I'd recommend bringing the following UNIX-y tools to bear:

* Doxygen, using the Graphviz package to generate dependency/inheritance graphs.  This will allow you to trace through the structure of the code up, down, left, and right in your browser.
* Exuberant Ctags if your editor supports it.  Allows jumping from symbol instances to definitions quickly.
* Cscope for more powerful source searching and navigation. Some editors can interface with it directly, but it comes with its own text-based front end.

These tools won't necessarily help you solve all your problems immediately, but may help with getting that 10K picture someone suggested earlier that you can then use to make a well-informed report to management and customers regarding the true cost and effort involved.

Good luck...

"I just got given a 200K line windows ( mostly MFC ) application which NEARLY works, that they would like out of the door quickly. Unfortunately the designer left without any hand over or documentation and it's been sitting around neglected"

This is so unbelievably typical in our industry. In at least 50% of the cases the previous dev. bailed out because he had build up such a huge technological debt over the course of the project schedule (usually not his fault, but the result of unrealistic timetables), that the weak foundations on which the whole thing balances look like they are collapsing and he is about to be go technologically bankrupt.
It is not uncoommon for the "nearly finished" project to take again 50-100% of the resources it took to get to the "nearly" point. The sad part is that the new guy/team is in the hot seat from day one with the PHB's breathing down his neck and constantly muttering about how on earth this is possible since the job was nearly done and implicitely (and often overtly) implying incompetence of the new team.

From Just Me to You Sir
"The sad part is that the new guy/team is in the hot seat from day one with the PHB's breathing down his neck and constantly muttering about how on earth this is possible since the job was nearly done and implicitely (and often overtly) implying incompetence of the new team."

---

Agreed.  It's a brutal, nasty situation to be in.  Doing a stupendously excellent job (i.e., actually getting this thing out "on time") would probably yield no recognition from nontechnical managers, while merely doing a good job might incur scorn from managers clueless on the  challenging technical aspects.  The best you can do, I think, is be in constant communication on why things are the way they are and hope for the best.

If I were in your shoes, I'd start with the main() method. Pare it down to practically nothing (comment out most of its calls), and get it working. Step through the method with a debugger to see how it works. Then do the same thing for each of the methods called within main().

Lather, rinse, repeat.

Eventually, you'll work your way through the codebase. You'll start to get a good idea for how the code works, and eventually, you'll be able to start making some changes to it.

Most importantly, as you learn things about the architecture and design of the code, drop some documentation into the source code. Otherwise, you're not really solving the single-developer knowledge problem. You're just becomming the next guy who's responsible for the whole mess.

"I just got given a 200K line windows ( mostly MFC ) application which NEARLY works, that they would like out of the door quickly."

is one thing...

"The main problem is that the app looks finished, all the pretty graphics are there, it just produces weird error messges, occaisonal lockups and sometimes the wrong answers."

is another thing entirely.

I bet you it does *not* nearly work.

Time to cover your backside. Others have mentioned time required, talking to management, action plans etc, so I won't. This is going to be a disaster and you had better make sure they know why. The quicker you give your assessment of the project the more credibility it will have. Credibility will increase when your predictions come true. A good plan will avert some problems so make sure they know the plan was responsible for averting the problem, not an incorrect prediction.

Incidentally, I just found myself in a similar position to this. Two weeks ago, I was dropped into an existing group, working on a J2EE business application with 860,000 lines of code (over 300,000 of which is XML configuration files) and I was asked (with a two-week timeframe, before a client launch) to fix some major presentation bugs in the calendaring interface. It has been somewhat stressful, to say the least.

>The main problem is that the app looks finished, all the pretty graphics are there, it just produces weird error messges, occaisonal lockups and sometimes the wrong answers. ( this is a medical imaging app - so not good ! )

It sounds like the app isn't close to being finished and you are going to have to communicate that if that is the case.


How does the code look?  Well commented, consisitent style?  What is your gut feel?

What happened to the old developer(s)?

Good luck with that!

Forget about reading books and learning new tools.  The first thing I would do in this situation is communicate the problems with management through a formal email.  Trying to fix problems in a 200k code base that you need to learn is a huge risk area.  What kind of unit and regression testing frameworks and processes are used?  Fixing a small bug could cause additional problems.  This is especially true if you don't understand the overall structure of the code.  Will the existing test environment catch these?  Be assertive and confident with management, but give them options as well.

Explain that what you are doing is the same as research and development, since you need to spend time observing an unknown system [the code base] to understand it in order to make it work.  It's next to impossible to give accurate timelines under these circumstances.

I'm curious about a few things:

1) Such a large code base was written by only one developer?  There's no one else that has any exposure to it?

2) What kind of testing has been done?  If the testing [development and QA] is thorough then you're in a much better situation.  However,  if the testing processes are weak [my suspicion] then most of the problems haven't been found yet. 

3) Are there any requirements or design documents?  If not, how did they design the test cases?

4) Is there only one developer on this project?  How many QA people?  How many development testers?  How many documentation resources?  Is there a project manager?

5) Is it possible that the previous developer was just coding ad-hoc based on informal internal feedback, and that there is no overall design to the application just hack after hack?

6) Is it possible to hire the previous developer as a consultant to accelerate the knowledge transfer?


This will not be an easy project.  Communicate clearly and honestly with management.  If they refuse to take responsibility for their own mistakes and just want to push the product out the door, beware of any political nonsense. Do what you can to help, don't take anything personal, and look for another project as soon as possible.

Good luck.

Everyone I think has come up with some good suggestions so far.  This would be my approach:

1) Create a completely new app.

2) Do not attempt to rewrite this new app from scratch, no
  matter how tempted you are to do so.

3) Instead, start with one function, and copy only what is
  needed from the previous app to get this one function
  to work. (including data structures).

4) If the app compiles, but the one function doesn't work,
  determine if it did in the previous code.  If it didn't
  in the previous code, then no loss (go to step 6), but
  if it did work in the previous code then:

5) Step through the previous code in a debugger.  Step
  through the new code in a debugger.  Find out why yours
  fails while the previous code succeeds, and:

6) For functions that never worked in the previous app,
  rewrite them in the new app however you'd like to.  For
  this step you are allowed a little bit of
  thinking/new coding/refactoring, but not
  for any of the others (due to time constraints).

And, as I believe Benji said, "lather, rinse, repeat".

It will not be easy.  But if you can divide a 200,000 line app into two 100,000 line apps, you'll have made a great deal of progress.  The more you can repeat doing that, the better.  Remember, you're *perfectly allowed* to decouple dependent things in the testing phase, just make a note to "recouple" things when you have more understanding of them -- which you will have after you've worked with the system more -- when a bit more time has elapsed...

It will not be easy.  But you can do it!

Wishing you luck (and clean compiles!)

Peter

I sense a gap in the market place. I can see the book title now:

"Virtually Impossible Tasks for Dummies in 21 days"

;-)

Seriously though, there is only one thing to do in this situation (if you can't get out of it).

Document everything! Each time you find a problem log it in a tracking system (or even just a text file that you email around each day). When you fix something log that too. When management see 59 problems fixed so far, 178 other problems identified they will revisit their assumption that the program was "almost ready".

If you just work away quietly it will look like your fault when you're not finished in a week or so and your verbal complaints about the software will seem like whining.

It's all about the right kind of communication.

And don't forget to document the action items that you placed on management e.g.

- provide requirements docs
- provide design docs
- provide project plan

When they say "we don't have any of that stuff for this project" it shows that your job is that much harder.

I've been in the same situation several times, and honestly you should just learn enough to completely hack it well enough to satisfy them to release it and get it off your hands, while continuously communicating to them everything that's been suggested about. If you try to rebuild it or do any kind of refactoring, it'll take at least a year because you're likely going to find a mess of interdependencies that will manifest as bizarre bugs far more difficult to track down than what you probably see now.

It is worth trying to get them to pay the previous programmer to come back for a day and explain what he can, starting from the top. If they won't, try contacting him yourself and explain your situation and he may do it for free out of pride (because it was probably his "baby" afterall...)

(After entering bugs in your favorite tracking system).
Every bug is part of a story.."I was in here and I did this, and clicked that, and got an error". So create a simple function to automate the clicks/etc to duplicate the error, code that should notify you when there is a PASS for EVERY assumption... this will help you walk through the code, and find the error. Some advocate given testing technology (xUnit or my own QTest for Delphi), but I'd just stick with the story+functiontest approach if its something huge.  It will help you later as well, since you can re-run all your tests (or mix and match) to see how the system behaves.

1) Polish up the resume.  It never hurts to have your resume up to speed.  Also, the previous guy might have quit for a reason - a reason you might have just inherited.

2) Everything Peter Sherman said.

3) I would add unit testing, too.  When you get a function to work, throw it in an automated unit testing (regression testing) framework so that as you make changes, you don't break things.

4) Work to change the expectation that it's "almost done."  Remember the 80/20 rule!  The first 80% of the functionality only takes 20% of the time - the last 20% of the functionality (and stability!) takes 80% of the time.  Find out how long it took the previous guy to get 80% of the functionality, because you have *four times as long left to go*.  Possibly longer, since you didn't write the damn thing.  Granted, this is the most pessimistic view of things, but remember that, "A pessimist is just a normal person who is surrounded by optimists."

5) Add printfs everywhere.  If there isn't already a good logging mechanism, and a good error trapping mechanism, add them the *instant* that you get the app to compile in the first place - you're going to need them - a lot.

6) Make UML diagrams of the parts you think are either most important, trickiest, or uncompleted (especially if they have more than one of those attributes).  If you don't have tools to make UML, try to get them (like VisualThought), or just take extremely careful notes and draw pictures on paper.

7) Ditto on the bug list.  Keep very careful track of all the work you think you need to do - bugs, enhancements, maybe even documentation and testing work.

8) *REVISION CONTROL*  If you don't have a good revision control system, start making manual backups (ZIP?) of each stage of your work.  (Possibly after every day!)

9) Once you get your application compiling, never leave for the day if it's not compiling again.  Your biggest problem right now is comprehension - and if you can't comprehend why something won't compile any more, then that's your biggest problem.  "Sleeping on it" will probably hurt more than help.

10) Don't be afraid to wrap classes with proxy classes of your own (especially if they add useful semantics for you, useful debugging for you, useful logging for you, etc.)  Don't be afraid to make things into pointers (or smart pointers, or whatever) in order to accomplish this, if you have to.

11) Keep a sense of humor about this whole thing.  You're going to need it.