Passing my own project on someone else - what to do?

Question

Often there are situations where a project is passed on someone else. And often this process is unpleasant for both sides - the new owner complains about horrible documentation, bugs and bad design. The original owner is then bothered for months with questions about the project, requests to fix old bugs etc.

I might soon be in a situation where one of my projects will be given to someone else so I can focus on my other projects. I wonder what should I do to make this transfer as smooth as possible. What i already have is a decent documentation, the code is quite good commented and i'm still improving it. Its a medium sized project, not very large but still its not something you can code in a week.

I'm looking for a list of things that should be done in order to help the future owner taking over the project and at the same time will spare me all those annoying questions like "and what does this function do, what purpose does this class have...". I know documentation is a must - what else?

Note: although my project is in C++ i believe this is a language-agnostic question. If there are things you think are specific to some language, please mention them too.

Answer 1

Documentation, but on all levels:

• API docs
• High level architecture: What components are there, what are their relationships and dependencies
• For each component, a high level description pointing to important code sections
• Tutorials: If you want to do X, here's how
• Data: What data does it use and how, database schemas
• Idioms: If you've created some idioms within your code, explain them

And, to start, give the guy a personal introduction to all of the above in person, hopefully doing some needed change in a pair programming way

Answer 2

If there is good documentation and commented code as you say, then you've done your part. Just make sure that the documentation includes high-level documentation (architecture, data flow, etc.) as well as lower module or procedure-level documentation.

If this is a situation where you can, I would strongly suggest you protect yourself with some type of contract that specifies what future support (if any) you will provide and for how long.

Answer 3

I think most of the problems can be avoided with just two simple rules.

1. Keep the code consistent with platform style guide.
2. Naming, naming and naming.

If the project is huge, then you just need to run some code camps with the new guys. There's no shortcut for this one.

Remember also that complaining happens mostly because new guy is not qualified enough, i.e. doesn't understand something. That's why it is important to keep things simple. And in case he is more qualified, then I guess you deserve it ;)

Some good advice where to start hacking/changing things is always better than documentation. Consider documentation as a backup material after you are familiar with the code, it should never be the starting point (except if you are exceptional technical writer with unlimited resources and time)

Answer 4

Documentation is one thing, getting it into the head of your new project owner another. IMHO this is a typical situation where "less is more" - the less documentation your colleague has to read to understand something, the better. And, of course, learning takes time - for both of you, accept it.

So

• instead of writing lots of documentation, make your code self-commentatory

• have all documents / source code etc. in a clean and well named folder structure

• make sure your build-process is almost completely automatic

• don't forget to document your deployment process, if it is not automatic, too

• clean-up, clean-up clean-up!

Answer 5

When taking over a project, documentation is of course desirable, but even more so is a good test suite. Trying to modify a program that you have no means of testing for correctness is a nightmare.

Answer 6

the new owner complains about horrible documentation, bugs and bad design.

I suspect that no matter what you would do, new owner will always complain about something. People are different, so something that looks easy to understand for you, will look horrible and extremely complicated for someone else.

The original owner is then bothered for months with questions about the project, requests to fix old bugs etc.

In this case you should clearly refuse to help. If you won't refuse, you'll probably end up doing someone else's job for free. If maintaining the project is no longer your job, then the new guy should fix his problem without your help. If "the new guy" can't deal with that, he isn't suitable for the job and should quit.

Its a medium sized project,

"Medium sized" compared to what? How many lines or code, how many files, how many megabytes of code?

I wonder what should I do to make this transfer as smooth as possible. What i already have is a decent documentation, the code is quite good commented and i'm still improving it.

I would handle it like this:

1. First, do a sweep through the entire code and:
   1.1 Remove all commented out blocks of code.
   1.2 Remove all unused routines and classes (I'm talking about "forgotten" routines, not parts of utility library).
   1.3 Make sure all code follow consistent formatting rules. I.e. you shouldn't mix class_a, ClassA and CClassA in same app, you shouldn't use different styles for putting brackets, etc.
   1.4 Make sure that all names (class, variable, function) are self-explanatory. Your code should be as self-explaining as possible - this will save you from writing too much documentation.
   1.5 In situations when there is a complicated or hard to understand function, write comments. Keep them as short as possible, and post only when they are absolutely necesarry.
   1.6 Try to make sure that there are no known bugs left. If there are known bugs, document them and their behavior.
   1.7 Remove garbage from project directories (files that are not used in project, etc.)
   1.8 If possible, make sure that code still compiles and works as expected.
2. Generate html documentation with doxygen. Reveiw it few times, modify code comments a bit until you're satisfied. Or until you're somewhat satisfied with the result. Do not skip this step.
3. If there is a version control repository (say, git repository) with entire development history, hand it over to a new maintainer, or give him(her?) a functional copy of the repository. This will be useful for (git )bisecting and finding source of the bugs.

Once it is done, and code is transferred to a new maintainer, do not offer "free help", unless you're paid for it (or unless you get something else for helping, or unless it is order from your boss which makes helping new maintainer a part of your current task). Maintaining the code is no longer your job, and if new maintainer can't handle it, he isn't qualified for the job.

Answer 7

I think for a situation like this the most important thing is a working, complete build that automatically compiles, documents, and tests the project. That way, there is a well defined point at which the new developer has it working. He can then figure stuff out from the tests and documentation, in principal.