Speed Up Your Debugging by Creating a Personal Coding Style

I have terrible handwriting.

Terrible for writing prose, that is. When it comes to doing mathematics, my handwriting is awesome. Why? Well, I very rarely write actual words by hand, but I’m always differentiating something with respect to time or rationalising some denominator. Over the years, I’ve developed my handwriting to help me do that — and you can do the same with your code’s “handwriting”.

I used to write my x’s as a pair of crossed lines. When I started learning algebra, I switched to writing them as two back-to-back c’s, so as not to get them confused with the multiplication sign.

Likewise, I started drawing tails on my little t’s so as not to mix them up with plus signs. I drew crosses through my 7s so that I wouldn’t confuse them with big Ts, and through my z’s because they looked like 2s.

I write little l’s in a cursive style, capital I’s with crosses on the top and tail, and 1s with a little hat because I couldn’t tell the difference at a glance. I make a sharp angle on the cap of a 5 in contrast with my very rounded S, draw Bs with a hard back to distinguish them from 8s, and always do little k’s in two parts because they look like h’s otherwise.

I could go on (and on, and on…) but my point is not that I’ve invented the definitive way of writing equations and oh my goodness you should all adopt it; my point is that I’ve developed a style that works very well for me. I can look at a page of my mathematical workings-out and quickly spot any mistakes I’ve made, but when reading someone else’s work — particularly someone from a slightly different background, like an engineer — I have to adjust to their personal style. Likewise, while they can certainly read what I’ve written, they have to do tiny translations in their head before really taking it in. Neither of our styles are better, they’ve just been tailored to what their writers find most intuitive.

It’s the same with coding conventions. Looking at a snippet like this makes me wince:

private function gen_rand_no(lower:int,upper:int):int {
	return lower+Math.floor(Math.random()*(upper-lower));
}

I prefer this:

private function generateRandomInteger( p_lowerBound:int, p_upperBound:int ):int
{
	return p_lowerBound + Math.floor( Math.random() * ( p_upperBound - p_lowerBound ) );
}

Perhaps you disagree. Perhaps you hate the second because of all the “wasted” space, or perhaps you hate it because I haven’t inserted enough space. We could all argue about camelCase vs. using_underscores, short function names vs. precise function names, the p_ prefix for function parameters and who knows what else — but in the end, it’s a senseless argument. There is no One True Coding Convention.

Don’t get me wrong; if you’re writing code for other people to use or share, it’s important to stick to the same core guidelines that the majority are using. But when you’re writing code that few or no other people are going to touch — whether that’s the internal workings of a component, or an entire Flash game where you are lead programmer — it’s just as important to write code that you are going to be able to read, and read quickly.

Developing your own conventions is key to this. Pay attention to restrictions you place on yourself, and think about whether they’re necessary. There’s no law against using long, precise variable names, but nor is it a crime to use terse, clipped ones.

This doesn’t mean you should ignore the ideas of other programmers. Remember, they have developed their coding style to make things easier for themselves, too, and you might be able to use their findings as a shortcut or starting point. (If you’ve developed any habits you find particularly useful, I’d love to hear about them in the comments.) Personally, I used gamepoetry’s UrbanSquall coding conventions as a basis for mine, and I think the idea of using different prefixes for different scopes of variable is brilliant. On the other hand, I don’t like that they insist on Booleans starting with is, has or can.

if ( isPlayerDead )

is just harder for me to read than

if ( playerIsDead )

so I started using the latter.

Now, when I skim through my code, looking for bugs, I don’t need to slow down for that split second it takes my mind to translate “if ( isPlayerDead )” to “if the player is dead,” because I just don’t have that delay when using my own personal style.

If you can get to the point where you can understand your code while you’re reading it, you’ll debug faster, and miss fewer errors. And, surely, anything that cuts down on debugging time has got to be worth trying.

Just remember: if you don’t like reading your code, you’re going to hate writing it.

Tagged as: coding, coding conventions, good practices, Programming