It’s been said that if you come back to code you wrote a few months ago, it might as well have been written by someone else. This is supposed to admonish developers to comment their code early and often, as much for their own benefit as for anyone else’s. However, comments are localized and are often used to give a high level overview of what a particular module or class is for, or to describe portions of code in which the control flow or the algorithm employed is hard to follow. Source control log messages often describe at a slightly higher level why certain changes were made (e.g. “Fixed a concurrency bug in exception logging” or the like). However, none of these types of low-level documentation give an overview of what was going on with the code when it was last touched. This is where the storytelling comes in.

To explain this, I’m going to start with a story about when I went to go see the third Pirates of the Caribbean movie. The movie started pretty much immediately after the end of the second movie (which I had seen nearly a year prior) without so much as a brief summary of what happened in the last movie. I suppose they expected people to watch the second movie on DVD right before going to see the third one. Literally the only thing I remember about the second Pirates movie is that Stellan Skarsgård is in it. The point is, I had no idea what the hell was going on when I saw that movie, and I think that’s the filmmakers’ fault for not reminding me what was going on before jumping into the action.

Coming back to old code is kind of like seeing the third Pirates movie without any refresher. TV shows like Lost, Heroes or Battlestar Galactica (or any serial drama, pretty much) all start each new episode with a “previously on X” segment, to remind us of what the crap was going on. They do this, because they know that we’re busy people, we forget things if we don’t write them down somewhere, and we have more important things to do in life than meditate upon the happenings in the last episode of Smallville.

Good developers pretty much have to remember a whole lot of stuff and keep it straight in their heads in order to be productive. And we’re usually looking for any tools we can find to help us out. This is where I think storytelling can play a useful role. Before wrapping up any block of work, we should consider writing our future selves a story about what we just did. Don’t be afraid to pump up the drama, or leave a few cliff hangers about work remaining to be done, either.  Here’s a (obviously contrived) example:

Previously on TimeZoneLib: This round of development was a hard fought battle between the dev team in one corner, and some broken-ass DateTime methods in the other. The time zone disparities were solved. But what about daylight savings time? I guess we’ll have to wait until the first Sunday of March to find out…

With apologies to real writers (and real developers). Developers will often tell stories about how users will/should use the software they are writing. This is extending the concept to tell a story about what the developers did to the software. The story will serve as a quick reminder to developers experienced with the product as to what was last done in a particular area. It’s obviously not a substitute for detailed documentation, of course.

This is really nothing more than another piece of the post-mortems that we usually do after a big project. However, I think it fills a real gap in the low-level documentation that code monkeys need before diving back into some code they’ve been away from for awhile.

January 17th, 2008 | | Subscribe to comments | Leave a comment | Trackback URL