[ Jocelyn Ireson-Paine's Home Page | Publications | Dobbs Code Talk Index | Dobbs Blog Version ]

Through the Toilet-Roll Tube

In the interests of creating employment opportunities in the Java programming field, I am passing on these tips from the masters on how to write code that is so difficult to maintain, that the people who come after you will take years to make even the simplest changes. Further, if you follow all these rules religiously, you will even guarantee yourself a lifetime of employment, since no one but you has a hope in hell of maintaining the code. Then again, if you followed all these rules religiously, even you wouldn.t be able to maintain the code!

Do you know that feeling you get when reading someone else's old code? You're staring at the statement in the middle of a procedure. You understand exactly how it updates its variables and arrays. You're pretty sure how it relates to the statements directly above and below; and you can sort of see its connection with those further away. Had you to change the procedure, say to print a transaction log instead of mailing one, you're reasonably happy you could. Though you're a little confused about some points at the margins. That parameter there: doesn't it create a Secure Sockets server, even though you didn't think the app used HTTPS? Well, perhaps it's an old thing never removed from the prototype: didn't that other programmer say they'd played with hacks to improve security? You're anxious about port9062: might it have something to do with the admin console? Ummm, that is worrying: must keep that at the back of my mind and try to look at it next week — or "tomorrow", as the boss insists on calling it. You're really not certain where that chain of pointers leads, and how much structure you would break should you change one. And you just don't grok those error messages; not at all. "Cld not, acccess hst handshk err": clearly some maintainer could neither spell nor punctuate. Amazing how they can get every last comma right in C++, but never in English. But "Error, function has no handles"? It's an exponential uncertainty field, a fisheye incomprehension lens.

Having suffered such things in too many projects, I was pleased to find my feelings reflected by Roedy Green in the essay from which I took my starting quote. He likens it to peering at code through the cardboard tube from the centre of a toilet roll. Here are Roedy's principles for How to Write Unmaintainable Code. (Another copy, not broken into pages like the original, is here.)