MichaelCrawford: in response to your entry on designing software, I have to say you are not alone.

Many of my projects start with some kind of skeletal code that's peppered with comments. The comments briefly explain what's going to happen, and they make it easy to see the big picture. They can be moved around or changed without too much fuss, since they don't actually do anything by themselves.

Once I'm happy with the scheme that's laid out in the comments, then I go back in and start dropping bits of code in between. I keep things straight by having XXX in the comments that haven't been given matching code yet. When the source file no longer has XXX in it, everything has been written.

This does lead to some interesting effects in the source down the road, since the comments can be braindead at times. You'll get a section of code that looks like this:

/* open the music db */

f = fopen(dbfn, "r");

Anyone who reads that (myself included) should go "duh". What they don't realize is that the fopen line came second, not the other way around. I could delete the comments, but I usually choose to leave them in.

As for the planning and such: I'll usually start the above sequence in main, then as things seem to have enough complexity, I'll spin them off into their own functions. A simple section might stay in main, but something that's relatively tightly wound and returns a simple code will go into a function. Those functions can then spin off other functions, and so it goes up the line.

This is not to say that I don't diagram things. I do plenty of that, sometimes even with pencil and paper when things get hairy. Some things just have to be laid out visually to get the sequencing right. The difference is that it usually happens after the program has existed for awhile, once it's grown up to the point where some things are no longer fresh in my head.

Back in school, one teacher wanted diagrams turned in with our assignments. I used to write the code and then generate the diagram later until she caught me. That's about the only time the written diagrams came first.