Turning the Perl program into a story

I started writing the Perl computer program nearly two years ago. I worked on it intermittently for most of a year, got it doing most of what I wanted, and then set it aside in the press of other things that seemed more urgent. This past summer one of the post-docs took it on - she wanted to learn Perl and bringing this model to fruition (= we publish a paper about the results) seemed like a great way to learn.

SO far so good. She's embellished the program and debugged it and now it seems to be doing just what we want. The most important words there are 'seems to' , because right now neither of us is confident that we really understand how the program does things, which means we can't be sure it's doing them right. I wrote the basic modules (procedures? subroutines?) of the program, but I forget how they work. And the post-doc has been able to use them without having to dig into how they work.

So now we're creating a narrative of the program, in which we try to explain in ordinary English all the things the program is doing, and how it decides what to do. A computer simulation is like a game of "let's pretend": let's pretend that these are the rules you must act by, and these are the conditions you start with. At certain points decisions need to be made, and the program spells out the rules for making each decision. At many points in our program the decision involves getting a random number (the computer equivalent of rolling the dice), but even here there are precise rules.

What we're trying to do now is write out a clear accurate description of what happens at each step. Of course such a description already exists in the program itself, but by recreating it in plain English we're forcing ourselves to make sure we really understand it. In effect we're making ourselves explain it to each other - in my experience that's the best way to be sure you understand anything you want to get right.

We hope this will only take another day or so, and then we can confidently put the program to work generating DATA!