Best Practices for Handing over Legacy Code?

As you have access to the developer you code ask:- Which modules were the most difficult to code/implement. What were the problems and how were they overcome. Which modules have generated the most bugs.

Which modules have resulted in the most difficult to solve bugs. Which bits of code he is most proud off. Which bits of code he would really like to refactor, but, has not had the time.

These questions will give you an insight into whats going to cause you the most problems, and, perhaps more importantly a handle on the thought processes and perspectives original developer.

I like the idea of picking the parts you mentioned. Intuitively, I would have followed a top-down but that way the most nasty parts buried deep in the code might not have come up until very late, maybe too late in the process. Your way makes more sense, I think.Do you have any suggestions for the "how to document" part?

UML? Text? – PersonalNexus Nov 9 at 18:54 @PersonalNexus.

You can carry this approach over to documentation as well. Ask which documents are most useful, and, which documents are unreliable or out of date (believe me 95% of documentation falls into the last category!). – James Anderson Nov 10 at 3:21.

Having been in a similar situation, I believe the following would also be worth consideration: Make sure you can make, and test, a deployment: Do you own deployment of the product, from scratch - and verify that this is identical to one done by the person who's leaving. This would make sure that any scripts and instructions are clear to you, and would catch any accidental oversights such as ingredients not having been checked in to your version control system. (I'm not saying that this would happen, just that if it has happened, it will be a lot easier to deal with now, before the person leaves) (This may not be relevant for you, e.g. If you already do Continuous Integration or Continuous Deployment, but it's worth mentioning, just in case...) Writing more tests: This is a really good way to test your understanding of a system.

It will enable (or force) you to look more closely at areas of the code, and will either confirm that the code is as bug-free as you suspect, or will reveal areas where you thought you understood the intention, but that actually you need to ask your colleague for clarification before he leaves Pair-writing of documentation: This is an effective way to write overviews. I'm suggesting that you get your colleague to describe a feature or area, and then you write it up, in documentation, in your own words. We found this was massively easier when done by two people together.

I'd put the writing of tests as a higher priority than writing of documentation, personally, as the tests will probably give you more - or firmer - understanding. Regarding Refactoring using pair-programming, the only thing I'd say is that there's a danger that this can become a bottom-less pit, especially given that you said you've only got high-level tests. You might find it ends up using way more of the available time than you'd intended.

1 more tests. There are never enough tests. – Sardathrion Nov 10 at 9:20 +1 for pair-writing of docs – Doc Brown Nov 12 at 10:55.

1 for the answers you already have in your question! Guided tour 10k lines of code is a lot, but I think it's still not impossible to have the other guy give you a 'guided tour'. You sit down together in front of the code and he takes you on a trip from the top to the bottom, working down the 'layers'.

You'd need to do it in short bursts - all in one go would kill both of you. Zoom-in, zoom-out The advantage of doing this is that while he's explaining it to you, he will almost certainly have some "oh, yes, there's this as well" moments that he might not if he was just trying to document it on his own. And your questions will help to focus in on the obvious-to-him-but-not-to-anyone-else bits.

This kind of zoom-in/zoom-out interaction is only possible one-on-one, trying to write or read something like that is unwieldy. Documentation I think you should both be independently documenting stuff - he should start at the bottom (in case you don't have time to get there together), and you should start at the top, on the basis of what you've understood of his guided tour and as if it was for someone else in a previous job I inherited a load of 'legacy' code, and only just had the time to document it before leaving myself :). Where's what?

The aim of most of this is for you to be able to get a feel for where stuff happens. So that given a particular bug or modification, you can very quickly find the place in the code which you need to concentrate on. You could test yourself by taking the list of old bugs and seeing if you can accurately predict where the problem was.

Pump him dry It doesn't matter if he ends up hating you (smile), your job is to get as much information out of that guy's brain as you possibly can in the time available. Make sure that you get management on your side, and that they prioritise knowledge transfer over "just fixing those last few bugs before he leaves" (unless you're fixing them together...).

1 for trying to fix some old bugs myself to test my understanding of the code – PersonalNexus Nov 10 at 8:18 "It doesn't matter if he ends up hating you" -- careful, "it's a small world" ;) – retracile Nov 10 at 22:29.

I would consider the most complicated, optimized-for-performance parts first. I would get him to first document those parts and explain them to you one at a time, then I would try to write tests against those parts (incuding before and after performance tests, so you can see if a new optimization makes things better or worse) and have the other person review the tests. This way, he documents and explains, you use the explanation to write tests (while he is documenting a different area), and his review will help make sure you understood what you should be be testing.

That way you also get additional test converage for some of the most critical parts of the application and documentation of the specialized performance optimizations. If there is time after covering those, I would next go through a similar process with the parts of the application which have most frequently needed change through the years but which are not in the first group of things documented. Then document anything that's left.

I suggest the following (in addition to what is already identified) - First, ask your manager to give you time to work with this guy as much as possible and try to sit with him whenever he is tasked of doing a change. You don't have to know everything he is doing but try to catch as much as you can. Most important be friends with him.

Treat the hand-over as a project and put a plan in place and involve the management. 0 - Make sure you know how to use the system. 1 - Make a clear inventory of the solution components, the source of each and where it lies (in diff.

Repositories) 2 - Get and if possible, manage, the passwords for the different servers starting now. Make sure you have all the admin account information 3 - Get the licenses of each external component unless its outside your scope (e.g. Special dlls, database, etc.) 4 - Get a written report about the current status of the system from the developer and your customers (if they are local to your company) 5 - Get the documentation for the business rules, calculation formulas, etc. You can do this with him. Ask him for emails, meetings information, user requirement documents, design documents and the like to be given to you.6 - Get a list of scheduled events (monthly runs of jobs, weekly runs of jobs) that the software has to respond to 7 - Learn the backup/restore procedures 8 - Understand the framework(s) used in building the application 9 - Get to the know the requested/expected/planned modifications and the status of any pending user requests.

Begin trying to identify how to do those on your own. 10 - Make sure your test and development environments are very similar.11 - Try to identify major dependencies (on other systems or between components) that can't be easily spotted. 12 - Identify and document the required versions of each software use and its vendor contact (if necessary) 13 - Identify any special tools he was using that you don't have, in case it could help you.14 - Get a high level system flow.

And start building your documentation library 15 - Understand how to manage user security for the application 16 - Get the bug log and try to understand the actions and how the action affected older data (if applicable) 17 - Know processes that takes too long and what do you need to watch for (e.g. Unusual file sizes, ftp of duplicate files, etc. ) where applicable.18 - Check the production server clock 19 - Identify where the configurations are and compare each environment configuration with the production to know what parameters are different and why 20 - Get this guy's contact information 21 - If the system is internal, schedule a a meeting with the system users (you need to know who they are and what the role each plays) and be introduced to them. Listen to what they have to say about the system and about their current problems if any. Make sure you are included in emails as early as possible (after your manager's approval) 22 - Assess your understanding 1 week before he leaves and report any problems you see as a risk Since you mentioned you don't have a database, this list got shorter.

Good luck.

1 for detailed ans. You can write your book :) – SSamra Nov 12 at 11:38 @SSamra: Thank you for the up lifting comment. I needed it.

:) – Emmad Kareem Nov 12 at 17:35 Very exhaustive and including some important points I might have missed otherwise, e.g. Involving management and our (internal) customers. – PersonalNexus Nov 13 at 4:42.

I think the best way to grok some large code is top-down approach. Try to understand the big picture first, and then gradually dig deeper into components one by one. Now at each level of digging, ask him to prioritize the parts that need most attention.

Have him explain you as much as possible, but always document it yourself. The best part about documenting it yourself is that when you'll come back later, you'll have no problem recollecting the same cognitive state you were in, when he explained it to you. You can far more easily understand what you wrote than what someone else did.In my experience two people documenting the same piece of code don't produce similar looking pieces of text.

This, I guess also solves your "what & how to document" issues. When he explains you everything, you can then decide yourself what you'll wish were documented when you return to the code -- and document only those parts. The idea is to first completely understand the code (in his presence), and then write/do everything that will make it possible for you to grok it later (in his absence).

By completely understanding the code I mean you need to get a feel of the big picture -- and how each component relates to this big picture. I've found it particularly helpful to keep track of how each piece adds up the whole. Don't try to comprehend anything in isolation -- never lose the sight of it's context.

Lastly, once you have done the above, proactively take the control. Decide yourself what pieces you need unit-test coverage for. What parts need to be (or can be) optimized, how can you refactor some component, etc. Trust that if you know the system, you can take all the decisions once he is gone.

– c69 Nov 8 at 12:30 Anything that makes it possible to restore the same understanding of the code you had when you were writing the docs. – greengit Nov 8 at 12:57.

I feel for you. A few suggestions: Tape every conversation you have with the leaving programmer! Ask for the motivation behind the "big" issues.It's good you understand the API, but dig for the internal decisions - why was the code partitioned as it is?

What are the responsibilities. Make an effort to really study the code. When you assume maintenance and support duties there is sometimes the pressure to "study the code while making progress".

Resist if you can, and really study the code. Look for scenarios. You know the API - see how the code behaves.

An example that comes to mind is that of a Fax module. As a user of the API, you preheps had to prepate a page image and send the code a command to transmit the page. Ask the leaving programmer to trace with you on the code to see how this scenario carries through.

Then, of course, go the "receiving page" scenario. 80/20 - try to cover the more common scenarios first. Consider a re-write.

If the code is old and the interfaces are well defined, maybe technology has changed enough to justify it. I hate to say this, but consider looking for a new job.

I like the idea of taping every conversation, so I can get back to his original words, after he is gone. Suggestion #7, however, not an option ;-) – PersonalNexus Nov 13 at 4:40.

If you want decent documentation reasonably painlessly buy a copy of Pascal Analyzer (PAL) I have used this on Delphi projects and it was great - they may now have split the documentation functionality off into a product I'm not familiar with (Pascal Browser) so you may have to buy both (Delphi itself supports refactoring in recent versions (the last 5 years or so). You did need to include everything in the dpr file for it to really work properly back when I was doing it so bear that in mind. If you want unit tests, download DUnit & start creating some tests with the original coder - that's probably a constructive way to use at least some of their time.

Though you have not mentioned about a backend database but assuming there is one you should Get the data model documented especially the columns and PK-FK Setup a sql trace and record all the queries which are fired while using the application. The order of execution of queries will give you a good idea about the flow of the application and also help in debugging.

Good point in general, but there is no database in my particular case. – PersonalNexus Nov 10 at 18:33 1 may be it will help somebody else – NRS Nov 10 at 18:42.

I am in same situation where our Architect moved to Australia and left over lot of legacy as he was with company from last 8 years. He him self inherited legacy stuff from previous Architect who was a contractor. You and others have already mentioned good points but here is problems we faced after he left may be you can prepare better ... 1) (Technical Person) Contact details of the customers he is dealing with.2) s account under which he bought softwares licences , keys which need be renewed every year and processes/costs to renew them.3) Document of Setup of third party software libraries/components and products which integrate with your products.

We struggled for 4 days to bring back a machine which was lost due to IT clearing up space and some wrong instruction passed to them.4) Documents/steps he is used to deposit source code to software Deposit companies eg Escrow. 5) There is still long list but may not be applicable to you also No amount of documentation can replace a real person so Keep his details handy , stay in nice terms and good luck :) Also I don't know if this is first time for you. For me I have worked with 5/6 employers and have always inherited code with bad documentation or no documentation at all.So along with all the documentation just stay positive :).

I cant really gove you an answer,but what I can give you is a way to a solution, that is you have to find the anglde that you relate to or peaks your interest. A good paper is one that people get drawn into because it reaches them ln some way.As for me WW11 to me, I think of the holocaust and the effect it had on the survivors, their families and those who stood by and did nothing until it was too late.