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.
{ 11 comments… read them below or add one }
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.
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.
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.
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 “
@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 😛 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.
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.
Yeah I much prefer Allman style… but I’m confused, isn’t that what UrbanSquall uses?
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!
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 🙂
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 🙂