How Should A Departing Programmer Organize Things For Successors?

Question

[Michael Hoffman]

A programmer on my project is going to leave in about a month. We stress the principles of A Quick Guide to Organizing Computational Biology Projects (disclaimer: written by this lab's principal investigator). I've stressed the importance of version control before, and he reports that major application code is all in version control, and run scripts are all in dated directories, such that it should be easy to find the script used to create a particular file in his dated lab notebook by looking at the surrounding dates.

His code is well-written and I haven't had much trouble figuring out how it works when I need to. My biggest concern is finding the right file. All the version-controlled application scripts should be described by a line in a README file, and I think I'll probably try to make do with figuring out where lab notebook files came from using the date and by grepping the name of the created files.

I also don't want him to spend too much time documenting when that is always imperfect and he could be working on new code or fixing bugs instead.

Are there any suggestions or things we didn't think of? Things you wish you had asked of programmers before they left your lab?

Answer 1

[Istvan Albert]

My tip: maintain a very good relationship with the departing individual.

No matter how well documented a project is, advice and comments from the original creator/maintainer can be extremely helpful later on. This cuts both ways; for the departing programmer good references from past employers are invaluable. So there is a mutual interest.

PS: from the article you've referenced I think you have a system in place that is as good as it gets.

Answer 2

[Pierre Lindenbaum]

Have a look at this question on StackOverflow:

What precautions should you take when a senior employee leaves?

Answer 3

[Giovanni M Dall'Olio]

For the future, consider adopting some Agile Programming rules/principles:

1. Write Unit Tests or at least rudimentary tests for all scripts. A test is a small program that check whether a script or program works correctly. If you modify a script written by someone else, it is likely that you will break some functionality accidentally; but if the person who is leaving has written tests for its code, you will be able to modify the scripts and use the tests to check whether you are altering them.
2. Make Pair Programming at least from time to time. If you follow all Extreme Programming rules at the letter, every script and program should be written by two people at the same time, sitting on the same computer, one with the mouse and the other with a pencil; however, you may do this only for the most important parts. The scope of Pair Programming is to uniformize the coding style of the programmers: you should always avoid to have people with very different coding style in the same group.
3. Move people around: from time to time, switch the tasks carried out by each programmer. Avoid having specialists which are the only people in charge of a specific project or task and that write code that it is difficult to understand for the others.
4. Do Collective Ownership of all scripts, or at least have a pool of scripts used by everybody and that nobody feel they are the owners. We are scientists, and we are paid to do science, not to become big programmers: however, people in bioinformatics tend to spend a lot of time in improving their coding skills. You should take advantage of this but at the same time avoid that everybody has its own scripts to do its analysis, and that everybody has a custom-made version of the same programs to make the same stuff.

In any case, you should also follow what otherpeople said in this topic: use a versioning control system, and document as much as you can. I like python's doctests which are a way to write documentation and tests at the same time.

Answer 4

[Tom Walsh]

The problems I've repeatedly come across are:

• Code with the same dependency hard-wired in multiple files, often with no documentation.
• Code that breaks with error messages that are of little or no use in determining what the actual problem is.
• Code with no test facility to work out what is going wrong.

At the point where someone is leaving, the only thing you can do is make sure the code is properly documented so at least you know where to look when it breaks. If possible, I'd get someone unfamiliar with the code to do a test run using only the available documentation and a copy freshly checked-out from version control.