Okay, so basically, this is just another rant in the long line of rants that no one listens to in life. Still, it’s my blog and if I want to rant, I can. So nya!

For a while I’ve had my head buried in someone else’s code. Ugh. Yeah. We’ve all been there. (We as in programmers at least.) When you’re lucky there’s good use of whitespace, good use of descriptive naming, and so the code pretty much documents itself. If you’re really freaking lucky there’s even enough comments added to the code that you get a good idea of what’s going on. And if you’re really really lottery-winning damned lucky there’s clear and concise internal documentation.

I admit, I’m not always nice enough to go the whole nine yards. Sometimes I skimp, because the code working is more of a priority than the code being maintainable.

But still, I’m a nice guy. I’ve been around the block long enough to know that I won’t always be the one maintaining my code. And sometimes even when I am, code can get complex enough that I won’t necessarily remember all of the ins and outs a year or two later. So I generally make an effort to internally document my code.

I wish everyone was as nice.

As I said, I had my head buried in someone else’s code. Code that, while (mostly) functional, is only a step away from the vagueness of formulaic programming. Code that (and mind you, this is in Python) uses lists (Python’s version of arrays) to store random variables in, like they were freaking FORTRAN common blocks! And I’m not even sure the author knew what a comment character looked like when he wrote it all.

Yes, it was that nerfed. No, I’m not exaggerating. Ye gods I wish I was.

And all I could think about as I added internal documentation and renamed variables to be self-documenting as I wheedled my way deeper and deeper into the code that wasn’t working right, was “Why the hell couldn’t this code be a little easier to maintain?!”

Ugh.

Still, having once upon a time, strangely timed right before male pattern baldness and grey hairs began creeping in, I had the joy of performing tasks like converting 16-bit x86 Assembly code to 32-bit and finding C++ libraries that could replace as much of the Assembly code as possible. Assembly code that wasn’t documented. Used in FORTRAN 76 code with that reverse if-goto logic because it didn’t have if-then-else logic yet. FORTRAN code where sometimes the authors commented according to that reverse logic, and sometimes according to modern order … only without saying so. So you never knew if a comment was explaining as it was, or as it should be - but wasn’t. FORTRAN code with common blocks that didn’t even always match up correctly. And spaghetti goto and continue statements all over the place. That in turn used the undocumented Assembly code.

I think it’s safe to say I’ve seen hell. And so my recent delve into someone else’s Python code could at least be said to be more like purgatory. Or maybe more like the second or third circle of Dante’s hell.

And then as I returned to some of my own code to work on adding new features, I found this lovely refreshing oasis of reason and sanity.

If there’s one message, even just one little message, that I could get across to all computer programmers the world over, it is this:

DOCUMENT YOUR DAMN CODE!!!

Thank you.