Transferring my own project to someone else - what should I do?

Question

Often there are situations when a project is transferred to someone else. And often this process is unpleasant for both parties - the new owner complains about terrible documentation, errors and poor design. The original owner then worried for several months with questions about the project, requests to fix old errors, etc.

In the near future I may be in a situation where one of my projects will be transferred to someone else so that I can focus on my other projects. I wonder what I should do to make this transfer as smooth as possible. I already have decent documentation, the code is pretty good, and I'm still improving it. His project is medium in size, not very large, but still not what you can encode in a week.

I’m looking for a list of things that need to be done to help the future owner take on the project and at the same time save me all these annoying questions like "what does this function do, what purpose does this class have ...". I know that documentation is required - what else?

Note: although my project is in C ++, I believe this is a language agnostic question. If there are any things that you think are specific to any language, list them as well.

Answer 1

Documentation, but at all levels:

• API docs
• High-level architecture: what components exist, what are their relationships and dependencies.
• For each component, a high-level description indicating important sections of code
• Tutorials: If you want to make X, here's how
• Data: what data it uses and how, database schemas
• Idioms: if you created some idioms in your code, explain to them

And to get started, give the guy a personal introduction to all of the above personally, hopefully

Answer 2

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

So

• instead of writing a lot of documentation, make your code self-comment

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

• make sure the assembly process is almost completely automatic

• remember to document the deployment process, if it is not automatic, also

• cleaning, cleaning when cleaning!

Answer 3

When accepting the project, it is desirable that the documentation is desirable, but, nevertheless, this is a good set of tests. Trying to change a program that you cannot check for correctness is a nightmare.

Answer 4

the new owner complains about terrible documentation, bugs and poor design.

I suspect that no matter what you do, the new owner will always complain about something. People are different, so something that is easy to understand for you will look awful and extremely difficult for someone else.

For several months, the original owner has been worried about questions about the project, requests to correct old errors, etc.

In this case, you should explicitly refuse help. If you don't give up, you are likely to end up doing someone else a job for free. If supporting the project is no longer your job, then the new guy should solve his problem without your help. If the “new guy” cannot handle it, he is not suitable for work and must leave.

Medium sized project

"Average size" compared to what? How many lines or code, how many files, how many megabytes of code?

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

I would handle this as follows:

• First, scroll 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 the utility library part).
  1.3 Make sure that all code complies with the agreed formatting rules. That is, you should not mix class_a , ClassA and CClassA in the same application, you should not use different styles to place brackets, etc.
  1.4 Make sure that all names (class, variable, function) are self-explanatory. Your code should be as explainable as possible - this will save you from writing too much documentation.
  1.5 In situations where there is a function difficult or difficult to understand, write comments. Keep them as short as possible, and publish them only if they are absolutely necessary.
  1.6. Try to make sure that there are no errors left. If there are known errors, write them down and their behavior.
  1.7 Remove garbage from project directories (files that are not used in the project, etc.)
  1.8 If possible, verify that the code is still compiling and working properly.
• Create html documentation with doxygen. Repeat this several times, slightly change the code comments until you are satisfied. Or until you are satisfied with the result. Do not skip this step.
• If you have a version control repository (for example, a git repository) with the entire development history, pass it on to a new maintainer or provide him (her?) With a functional copy of the repository. This will be useful for bisecting (git) and finding the source of errors.

Once this is done and the code is handed over to a new maintainer, do not offer “free help” unless you are paid for it (or if you do not receive something else to help or if it is not an order from your boss that helps to help new maintainer in your current task). Maintaining the code is no longer your job, and if the new maintainer cannot handle it, he is not entitled to work.

Answer 5

I think most problems can only be avoided with two simple rules.

• Save the code in accordance with the platform style guide.
• Naming, naming and naming.

If the project is huge, you just need to run a few code camps with new guys. There is no shortcut for this.

Remember also that complaints happen mainly because the new guy is not qualified enough, that is, he does not understand anything. This is why it is important to keep things simple. And if he is more qualified, then, I think, you deserve it;)

Some good advice on where to start hacking / modifying things is always better than the documentation. Consider the documentation as back-up material once you are familiar with the code, it should never be a starting point (unless you are an exceptional technical writer with unlimited resources and time)

Answer 6

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

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

Answer 7

I think that for such a situation, the most important thing is a working, complete assembly, which automatically compiles, documents and tests the project. Thus, there is a clearly defined moment at which a new developer works. He can then describe the material from the tests and documentation, in principle.