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!

4 comments:

  1. This is a good exercise if you're starting out in programming. With time and experience though, you won't need to go through the process of translating code into English - it will just happen instantly in your head. You'll write something like "for($i = 0; $i <= 100; $i += 2" and just know that it counts from 0 to 100 in steps of 2 without giving it a second thought. In a way, your code will become "English" - rather like becoming fluent in a foreign language, you won't be aware that you are mentally "translating". The best way to understand code is to keep writing code.

    People say that the best code is self-documenting. I don't think that you need comment line-by-line; just comment the start of each subroutine or procedure to briefly explain what it does and highlight any lines that can cause problems: "## fails if N > 10!" and that sort of thing.

    It's also worth bookmarking a few of the excellent websites that contain tutorials, tips and advice. The O'Reilly sites are very good e.g Perl.com. I also like PerlMonks. Be warned though, solving programming problems is at least as fun and addictive as solving biological problems.

    ReplyDelete
  2. Hi Neil,

    I already know how addictive programming can be for me. It's a valuable tool for making our hypotheses rigorous; every few years I let myself get hooked, and then I kick the habit so I can keep my science embedded in reality. This means I've never even gotten close to being fluent in a programming language.

    Our code is already quite lavishly commented (we're good about that), but reading over the comments is no more a guarantee of understanding than is reading over a textbook. I need to be make sure I understand WHY we want ## to fail if N > 10.

    ReplyDelete
  3. And thanks for the Perl support links. We ahve a few already, but they're usually over our heads. We were hoping to be able to hire a Perl-whiz undergraduate as a part-time advisor, but they're scarcer than hen's teeth around here.

    ReplyDelete
  4. I would love to read Heather's translation when it's done. I have tried reading through the program and existing comments and regrettably found it very hard to understand - once I have read the translation I can go back to the original comments, and also have a go at writing a draft paper.

    ReplyDelete

Markup Key:
- <b>bold</b> = bold
- <i>italic</i> = italic
- <a href="http://www.fieldofscience.com/">FoS</a> = FoS