Awards may not be always on time, but sometimes they come. And when awards come from your co-workers, who often understand your job better than your boss does, that’s even better. That happened to me today, and I think it is a story that is worth telling.

At one of my previous employers, we needed to mass-load accounts into a custom mail system, which used a relational database to handle the userbase (why not an LDAP directory? Don’t ask!). Customers would send us two CSV files (or Excel files which we would convert into CSV) with the accounts information, and I wrote a Perl program (and a handful of classes) that would do just that: read the two files, create the accounts in the DB, and create a shell script to fix the filesystem part. …The specification for the script just required it to be able to do a one-shot massive account creation: the customer would manage their domain on their own afterwards. However, I knew that things could change and I’d have to go back to the code later. So I started to write my program with these principles in mind:

• comment the code thoroughly: every unit of code performing a certain action should have a comment on top of it that explained what that unit was supposed to do
• write the comments in English: if I needed to show up some code on public mailing lists/forums while creating the program, or if someone else had to do it if I left the company, that would make things much easier
• make the code chatty on errors: when something fails, throw out all the information that is possibly needed to debug the problem.

A few days ago, an ex colleague of mine (whose name I’ll change in Mario here, so that you can’t track him back 🙂 was having problems with the script and asked for help. I didn’t even remember I created it, but a stroll on the main script was enough to connect all the bits and pieces, thanks to the comments. In half an hour, and without reading the code of the classes, I pinpointed what the problem was: they were trying to use the script for a mass-update on an already existing domain; the script was not designed to do that, and choked.

There were a few possible workarounds, but none of them was nice. The only real solution was to change one of the classes, but it required more time than I could spend on the issue. I gave some suggestions to Mario on how to solve it, and wished him good luck.

That happened late last week, so today I wanted to touch base with Mario and see how it went. Here’s a narrowed down translation of our chat:

Me: so, solved?
Mario: yes! Jo fiddled with the script for two days and found the way to fix it; we ran the mass-update yesterday, and it worked well.
Me: WOW! Do you mean that Jo had to study and change my code to enable updates? Poor thing!
Mario: he did, yes. And I think his comment says it all: “f***! Who wrote this code really knew what he was doing!” 😀
Me: 😀 Thanks, that’s so kind of you!
Mario: We mean it! All the comments you spread in the code made clear that you put things together sensibly; I am a Perl illiterate, and nonetheless I was able to understand what was going on in the code.

Mario and Jo, I want to let you know that I now have the log of this chat in the portfolio of my best professional achievements. Thanks a lot for it.

There are people who say: Perl is unreadable, period. This proves the opposite. I think that any programming language is as readable as the author of the program makes it. I always try to write readable code when I am given a chance to do it, and I am happy to know that I succeeded (at least, this time 🙂