What Happens When You've Scratched the Itch?

Open source software has been described as starting off as "scratching a developer's personal itch". In my experience, this definitely bears out. Problems that interest me become software that I want to do in my own time. Problems that aren't especially interesting (perhaps even boring) do not become software I write in my own time; usually someone has to pay me to do it. And sometimes I am truly fortunate in that I am both interested in the problem and I am getting paid to come up with a software solution for the same problem. In all honesty, I am a bit of code monkey—anything remotely interesting or intriquing (read: "bright and shiny") usually draws me in, even when the larger project might sound boring to the average guy on the street. What can I say? I love what I do.

But let's focus on the scenario that Raymond is specifically referring to: software that gets written by a programmer in his or her own time, that they are not getting paid for. A lot of this software now ends up as open source or free software. A significant portion (nay, a majority) of the code that allows you to view this post is based on such open software. It may be governed by any number of open or free software licenses (GPL, BSD, MPL, CPL, Perl Artistic, and more). But in the end, it all boils down to some guy or gal hacking together some software, cleaning it up (or maybe not), slapping a usage/copy license on it, and pushing it out into the hard, cruel world that is the Interweb of connecting tubes.

I am one of those guys or gals. I push out quite a bit of code out into the bazaar, where anyone can download and use it. I like writing software, and either I'm wearing the wrong kind of sweater or I have dry skin, because I seem to have a lot of itches. This means that I'm pushing out all sorts of code from time to time.

But if you look at the list of my software, you'll notice something. Some software gets written, and it seldom gets updated. This could be because I'm that good and my software doesn't need updating. But the grimmer truth is that the software doesn't get updated because either the itch is scratched (and interest wanes) or because the software solution itself has become outmoded or irrelevant.

If you look at SourceForge or CPAN, you'll find the problem writ large across the global developer community. Software is fun to write when you are interested, and it's a bit of a chore when you aren't so interested. So when the itch is gone or the software solution isn't as fun as it used to be, software starts to get neglected. Updates become less frequent. Bit rot starts to set in. Pretty soon, the solution becomes all but a footnote in time (or in this case The Wayback Machine).

Now, don't take any of this as a criticism on open source or free software—because it is not. This is, instead, an observation of the reality of writing open source software. While so many of us programmers love to write code and derive quite a bit of pleasure from just the act of writing it, we get even more pleasure from someone else using our software and also thinking it is cool. So what happens when the project isn't as exciting anymore, not as relevant, and no one is using it?

Well, it doesn't get updated. It collects dust. And if things change too much and it sits too long, it might start to suffer from some code rot.

Now a lot of people might see this as reason not to use some coder's little project, or some project that hasn't seen too many recent updates. But, of course, they'd be wrong ;-) Here's the thing: any code that actually works and actually meets your needs—that's very, very good. If it is open source, who cares that it isn't maintained? You have the code. Even better, it's finished and working! So download load it and integrate it according to the usage license. Drop the creator an email—they'll appreciate it! And who knows? They might be willing to dust it off and add your updates.

So what do you do then, if this is the reality of little software projects and toolkits? What do you do when you have scratched the itch? I'm glad you asked!

You document ever single API, interface, and use case.

Document, document, document! Document for your own sanity, if for no other reason. Your greatest enemy is not code rot, but code complexity and your own addled brain. Perhaps no one else will ever use your code, but the odds are that you will—even if it is just copying and pasting rather clever tricks into newer or unrelated projects. So document your code, because what seems elegant and obvious today is going to seem broken, confusing, or downright inscrutable six months from now.

So document your actual code, especially all the tricky bits or any of the hacks you needed to get around some broken interface. But in addition to documenting all the tricky bits of your code, document your classes, your interfaces, your APIs, your configuration options, you installation steps—everything and anything someone would need to use your code if they weren't as brilliant as you. Because that not-so-brilliant person is going to be you in six months.

You add all this documentation for you, but the result is that your code is cleaner, easier to understand, and easier to use. Which makes your life easier later, but it makes your code more likely to be used by others.

Maybe no one will ever use it. But you can move on to your new itch with a clean conscience now. Anyone could download your code and use it, thanks to all that good documentation. And who knows? Maybe that person will be you in a year or two—and boy, will you be thankful you did all that documentation ;-)