Do what I say...

I always tell my students to think before coding: that time spent designing and documenting their programs is time well spent. And, I mostly follow that advice. And then there's the occasion that I don't, and I'm reminded why documentation is such a good idea (actually, I'm not reminded so much as driven crazy by the fact that code I once understood is now utterly incomprehensible to me). A case in point comes from my expert systems class, which I am preparing to teach. (Lest you think it's a bit late, my school is on the quarter system, which truly sucks, but which means class doesn't start for a few days yet.)

In this class, I use the JESS expert system shell, which is written in Java. One of its very nice features is that it can easily be integrated into other Java software, and that's what we so in this class, using the expert system to build a player for Wumpus World. Wumpus World is an elaboration of the old text adventure, Hunt the Wumpus, in which players wander around, looking for gold, avoiding falling into pits, and avoid (and/or try to shoot) the Wumpus. In this case, we use a Java version of Wumpus World that includes a server that supports multiple client players across a network. The original code included a very simple example player. The students' task is to develop a more sophisticated player using JESS.

Now on to my stupidity. I spent some time puzzling out some of the Wumpus World code and figuring out how to interface JESS to it. Two years ago. I always intended to document what I figured out, but "didn't have time" to do it right away, let it sit on my desktop for a while, then things came up, and yada yada yada, it's two years later and I haven't a clue how the code works. Now I wish I had spend what would have been perhaps an hour or so writing up some documentation. I remembered that there were two versions of the code, corresponding to the two ways that JESS can be interfaced to Java: with the server communications encapsulated as an object that is manipulated from JESS code or with the JESS engine as an object controlled by a modified Java player. That's about it, until I had invested another half day working out the details. We all need to be reminded of the benefits of good work habits from time to time. I wonder if my return to meticulous documentation will last longer than my post-dental checkup flossing regimen...

Topics: software development, documentation, expert systems.