Critical Section


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.

Home
Archive
flight
About Me
W=UH
Email
RSS   OPML

Greatest Hits
Correlation vs. Causality
The Tyranny of Email
Unnatural Selection
Lying
Aperio's Mission = Automating Pathology
On Blame
Try, or Try Not
Books and Wine
Emergent Properties
God and Beauty
Moving Mount Fuji The Nest Rock 'n Roll
IQ and Populations
Are You a Bright?
Adding Value
Confidence
The Joy of Craftsmanship
The Emperor's New Code
Toy Story
The Return of the King
Religion vs IQ
In the Wet
the big day
solving bongard problems
visiting Titan
unintelligent design
the nuclear option
estimating in meatspace
second gear
On the Persistence of Bad Design...
Texas chili cookoff
almost famous design and stochastic debugging
may I take your order?
universal healthcare
entertainment
triple double
New Yorker covers
Death Rider! (da da dum)
how did I get here (Mt.Whitney)?
the Law of Significance
Holiday Inn
Daniel Jacoby's photographs
the first bird
Gödel Escher Bach: Birthday Cantatatata
Father's Day (in pictures)
your cat for my car
Jobsnotes of note
world population map
no joy in Baker
vote smart
exact nonsense
introducing eyesFinder
resolved
to space
notebooks
where are the desktop apps?