Hey look! Blogger's back from the hack attack, apparently, so it's open season on more random freakinname spewings.

Today's topic is documenting not only your code but what the heck the code is doing, and our case in point is Furthurnet, the peer-to-peer music trading service that only deals in legal bootlegs from bands that allow taping. I use it for tons of great free music, and have managed to collect a pretty good helping of Black Crowes sets, which is especially helpful since the band is, um, "taking a sabbatical" right now. Listening to a Los Lobos show from Furthurnet right now, actually.

Just to continue that tangent for a second longer, Los Lobos really is a good show. I managed to see them in Asheville, NC one summer quite some time ago with some friends. We didn't know their stuff from a hole in the ground other than the theme from La Bamba, and kept annoyingly chanting for them to, "Play the one we know!!!" They really had a good time with it, more than once playing the first few bars of La Bamba before going into another song. The bass player, iirc, was laughing to beat the band (har har) before they finally, and quite kindly, played La Bamba for us. Anyhow, the lesson learned is that they are a good-natured band which really knows how to rock. The covers and other songs they played ranged from Jimi Hendrix to more run-of-the-mill Mexican joints. Great show for $10 and I'd catch them again if I could.

Anyhow, back to the blog...
Furthurnet is a neat app, but you can tell it was mostly written by one person when it was initially concocted. It's scary how you can sit down over a weekend and hack something out quickly that does almost exactly what you need it to do without writing up a single document detailing what it is you're doing.

In a past project, we had planned to use XML to store our app's users' data in a text file when they saved their progress. Well, three or four months, iirc, passed and the XML programming team had flubbed up twice, producing no usable code and basically only showing they hadn't quite gotten the hang of XML. To meet scheduling deadlines, I came in one weekend and wrote I/O modules that used some wack format I rolled as I went to store the data in a text file. It worked, and I got it up and running in a weekend, but *sheeeeow-dog* it was ugly.

Every "object" stored in the hacked text file had its own tags, usually delineated with lines like, "@#$Begin Issue Section" and "@#$End Issue Section". This, in theory, made it easy to refactor later by using CDATA sections in an XML file, but let's look at the task that lay ahead -- you had to figure out each item of data that needed to be gleaned from the GUI, translate the output from my weekend code into something solid with error-checking, formulate a good XML schema, etc etc etc. Needless to say, the final version didn't have XML, even though it wouldn't, all things considered, have been that hard to add.

If it wouldn't be that tough to add, why wasn't it added, you ask? Well, I'd hardly taken the time to document my homespun text file format when I'd written it (I finally did after the app's release so that XML could be added to another, later version). New additions to the file later in the project had added some ugly hacks to the file format to account for backwards compatibility. The code, esoteric though it was, started out fairly readable, if I do say so myself, but by the end we had a commented code but an undocumented, slightly out-of-control protocol.

The bottom line is that if a new team came in to rewrite the I/O to take advantage of XML's strengths, they were going to be forced to learn my weekend code, by now hacked and extended about five times.

Same thing has happened in Furthurnet. They've got some code that worked in one guy's mind, but there's no document to cover the protocol. Now that the new team's in -- in this case just new open source programmers -- each new programmer is forced to read every bit of the much-more-sparsely-commented-than-even-my code to figure out what's going down. This makes quick moves to new platforms or technologies a realtively difficult task. The documentation and code are one. This is fine on a one-person project, but not so good when you're looking for code that can outlive your stay on a project.

What's the lesson here? I think it might be that I can't complain that I'm having to spider through every file to port Furthurnet to Mac OS 9- on the weekends because I'm guilty of the same foible at times. But I also think too many people are unable to see what's going to happen down the road if they don't document not just the code but the software program's technical aspects before calling something done.