<<< W=UH

Home

Thursday, January 02, 2003 11:03 PM >>>


Turning Over Software

Thursday,  01/02/03  11:26 PM

Many of you are programmers, like me.  One of the hardest problems we face is turning over software.

A big part of the joy of programming is the act of creation.  Your code is uniquely yours, a work product which is intensely personal.  It may solve a business problem or automate a tedious task or otherwise do something useful, but it is also a work of art, a personal creation.  You know what I mean, I know you do...

But it is critical that someday each piece of code be turned over to someone else.  Programs are not static creations like buildings, they are more like gardens.  They have an initial plan and form and implementation, but they require ongoing care and maintenance, and enhancements.  If you don't turn your code over to someone else, eventually you will spend all your time caring for your existing code, and you'll be trapped.

In order for programmers to be productive and happy, they must feel a sense of ownership.  This is why when you turn code over to someone else, you have to give it to them completely - it has to become theirs.  It is tough enough to work on code someone else wrote without feeling like it is someone else's code.

There are two things you should do to make turning over code easier on you, and easier on the new owner:

  1. Finish it.  Now no code is ever really finished, but it should be at some reasonable state of completion.  Things should work, or at most there should be a well-defined list of bugs to be fixed.  The code should be feature complete, or at most there should be a well-defined list of enhancements to be made.
  2. Stay out.  Really.  Let the new owner be the owner.  They must have the freedom to change things, even stylistic things that have no actual functional effect.  It's like selling a house - you can't tell the new owners how to decorate.  This doesn't mean you can't answer questions or be helpful, of course.

Note that one of the things is not "document it".  I don't really believe in internal documentation.  There should be copious and accurate comments in the code, of course, and you should turn over whatever specifications and user documentation exist, but writing new documentation for the purpose of turning code over is time-consuming and rarely helpful.

The turnover itself should be a well-defined moment in time.  All the source should be turned over at once, if possible, along with whatever documentation exists, and along with bug lists and enhancement descriptions.  Give the new owner a 10,000' roadmap - do this in person, interactively, at a whiteboard if at all possible.

If relevent or possible, build the code with the new owner, and go through a sample debug session.  This gives them the end-to-end knowledge they'll need to actually "do" development.  You might think it is simple - just a Visual Studio project to be built - but do it anyway.  You'd be amazed at all the little things which come up during development ("oh yeah, that header file is in this directory").  Debugging is even more idiosyncratic.  During the course of development, you figured out the best way to do it, and this is part of the campfire knowledge which should be shared.

It is good to identify some simple first tasks for the new owner to perform, to foster familiarity with the code and overcome the intimidation factor.  Be as helpful as possible for these first tasks, and give the new owner as much credit for performing them as you can.  You want them to feel a sense of accomplishment right away.

I've spent much of last year building some code which I'm going to turn over in the next few weeks.  I'm not looking forward to it.