The Code Makes My Eyes Bleed

Not often do you stumble into projects that are pristine. I certainly haven’t anyway. Almost every project I’ve been involved with has required some degree of unfarking to bring it to a close. But, surely there are things that we can do to make it so that those who have to come in and “finish” don’t have the undying urge to gouge their eyes out with rusty spoons?

In general, documentation is a good idea. We all know what I’m talking about, but why don’t we do it? It takes time, it’s not maintained, and who really reads it anyway? Everyone reads it! Assume that anyone will read the comments you make in your code. It’s a very easy way to get inside someone’s head. Today I was trudging through some code and had to harass our Sr. Engineer countless times to figure out why <insert snippet of code> was there. Half the time I asked he said, “hmmm…I don’t know.” It then took the two of us cruising the codebase to figure out the purpose.

The primary argument against documentation seems to be that the code should be readable on it’s own. News flash- it never is. I may be the brightest coder in the world, I’m not…but go with me, but trying to read the code that other people produce can be painstaking. Hell, I have a hard enough time reading the written language of some people, let alone code. So please, document what you’re doing. You’ll save everyone time.

There are many ways to accomplish the same task. Know this. My solution for a specific problem and yours may be completely different, in fact I would bet that they are statistically more likely to be different. We all have different backgrounds and standards so things will be different. But, that doesn’t mean that you have to ruin any hope that someone can jump into your code.

I’ve worked on projects where the code was like a never ending maze. Sure there are languages that allow you to do some pretty cool things. You have functional languages, recursion, delegation, list comprehension, etc. and all of these are incredibly powerful. However, making your application only work by passing function pointers around confuses the hell out of some great developers let alone the ones that are likely to maintain the code! Be kind to others. If you’re not you’ll likely be sitting on tacks tomorrow.

How would you like to wake up tomorrow and be called “a_32″? Ok, then you’re weird. I’d be a bit unhappy. I’m also unhappy when I see code riddled with that. How long does it take to type arrayList32? Honestly. I hate the numbering and all that too, but that’s just irritation. Make your names a bit more descriptive. Nobody is going to be able to take a codeset riddled with alphabet soup and make sense of it. if it’s a Hashtable of Sessions, use something like “session_table”, or something similar.

We all have to get better with these things. I know I do. But, think about the people that are going to be fixing the problems you create today and remember that they likely know where you live at least 8 hours of the day.