Speed Up Your Debugging by Creating a Personal Coding Style

by Michael James Williams on February 13, 2009 · 11 comments

in Articles

I have terrible handwriting.

The quick brown fox jumps over the lazy dog

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.

An x and also a cross

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.

t7T z2

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.

lI1 5S B8 kh

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:

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

I prefer this:

?View Code ACTIONSCRIPT3
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.

?View Code ACTIONSCRIPT3
if ( isPlayerDead )

is just harder for me to read than

?View Code ACTIONSCRIPT3
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.

{ 11 comments… read them below or add one }

ellison February 13, 2009 at 2:33 pm

yup, I used the second one which is having the first bracket below the :void. I learned this from tutorial and I found it easier to read.

Shorter variables is for optimized codes.

I used to write if(isActive), now I think I would use the later one haha.

You are right about this, since if you would want someone to help you debug your code, it would be easier for the person to understand if the code lacks of comments.

ellison February 13, 2009 at 2:39 pm

wow, after reading about urbansquall coding, I found out about the boolean part where they use isPlayerActive. It makes sense to me as well to use it as variable boolean. It came to me naturally.

Brian Yamabe February 13, 2009 at 5:05 pm

I hate your coding style ;-) I probably use the antithesis of everything you do, except precise function names. But I couldn’t agree with you more.

Make the style your own and evolve it as necessary. If you’re working on shared code, use the style that already exists so you don’t confuse the reader.

Didds February 13, 2009 at 6:17 pm

Cool advice :) One thing though, there’s a random “t” near the top… Just thought I should mention it xD

“differentiating something with respect to t or “

MichaelJWilliams February 13, 2009 at 6:22 pm

@ellison: Yeah urbansquall is great! Gamepoetry is an awesome site all around, actually.

@Brian: Haha, glad I didn’t go with my original title, “Guys, my coding style is awesome and you should all use it”.

@Didds: That’s actually intentional :P I originally wrote “with respect to x” but changed it to t for… some reason. I’ll make it “time” instead so that it reads better.

Nick Wiggill February 15, 2009 at 4:19 pm

Yeah, Urban’s conventions are good except for one or two little things.

BTW I still cannot stand 1TSB and KNF indent style, though (which he uses, although in a neater variation than many I’ve seen). I mean come on people, what is so difficult about lining up your braces? Do you not see that this benefits you? Allman style indentation is One True Style, and what I learnt C++ in at college. It also happens to be very similar to Kernigan & Ritchie style (the creators of the C language and ultimately the guys who defined most of todays ECMA-style language like Java, AS, even PHP)… you’d think they’d know what they were doing, right?

Excuse the rant.

MichaelJWilliams February 15, 2009 at 4:36 pm

Yeah I much prefer Allman style… but I’m confused, isn’t that what UrbanSquall uses?

Nick Wiggill February 15, 2009 at 4:46 pm

Hmm, mostly. I was just looking at the EntityContainer class he wrote, where he uses this…

“package com.urbansquall.serenity {
import flash.utils.Dictionary;

public class EntityContainer…”

at the top of the script. But I think you’re right actually, I’ve unfairly pinned the use of evil indentation on innocent ol’ Urbs!

MichaelJWilliams February 15, 2009 at 10:54 pm

Aha, I see, I hadn’t noticed that. At least you didn’t accuse him of using Hungarian notation. Call me crazy but I think he may have minded that :)

Nick Wiggill February 16, 2009 at 8:47 am

That thing is an abomination. As Linus Torvalds so aptly described it, “Brain Damaged”.

It’s always nice to see the big names using such simple terms :)

Leave a Comment

Writing code? Write <pre> at the start and </pre> at the end to keep it looking neat.

Anti-Spam Protection by WP-SpamFree

Previous post:

Next post: