Adopt Some Coding Conventions for Projects: Sloppy Code SUCKS!
I am writing this article in the hopes that you will learn from mistakes that I have made. Let me just tell you...sloppy code SUCKS! Once you start getting into bigger projects (or even not such a big project) and even worse when you start to work with others and share code things can become a mess. So I am hoping some of you with no coding standard or no idea of how to "properly" structure your code will get something out of this and decide to do the same or at the least come up with your own standard and stick with it.
Occasionally I do tweak or add to my standards but for the most part I really do keep everything the same.
Currently I've been improving some habits of mine (mainly things like spacing and brackets etc) a bit so my older code is a little sloppier than my newer stuff which is okay. I also want to first point out this article by GamePoetry which links to the "UrbanSquall" coding standards. Those are basically what I stick to except for the few additions / changes mentioned below.
So let's get started.
Class properties / Members
Public
The idea here is to always avoid using getter/setter functions whenever possible. Well, atleast for anything that would be called once or more each frame. If it's an obscure variable that is rarely called or used for something that isn't speed related you can use them...otherwise NO. Anything that is both gettable/settable will be simply written as it is:
//it probably wouldn't matter too much if you externally modified this variable public var maxSpeed:Number;
Read-Only
In order to decipher between variables that should only be read-only I will use an underscore to define them as follows:
//obviously you wouldn't want to externally change this variable... public var _bulletsLeft:int;
The speed difference of NOT using getters/setters can be very apparent with something like a "Vector" class where the 'x/y' variables are public. This adds probably 20-30 FPS to a demo with about 2-3000 sprites all doing world bounds wrap checks etc. Just imagine the speed difference when ALL of your code complies with this.
Obviously sometimes we may want to reduce the "_bulletsLeft" safely so in that case create your function "shootGun()" inside the class that holds "_bulletsLeft" rather than implementing some external code to reduce the "_bulletsLeft" variable. (This is more of a proper OO design practice: 'Encapsulate Change')
Private / Protected
For all properties usable only by the class that created them we will use the m_:
//this helps avoid naming conflicts...which is good! private var m_beanCounter:int; protected static var m_nextID:int = 0;
Naming Conventions
Booleans
Any boolean properties and functions will always be structured in question format. They are followed by the words: "is, has, can, does":
public var _isCollidable:Boolean; public function doesRayIntersectCircle(rayOrigin:Vector, rayHeading:Vector, circleCenter:Vector, circleRadius:Number):Boolean{ //code } private var m_hasGun:Boolean; protected var m_canComeToTheParty:Boolean; // lol
Constants
All constants will be in caps with phrases separated by underscores:
public static const HEAVY_ARMOR:int = 0x000001; public static const WOODEN_SHIELD:int = 0x000010; public static const SLARGH_FIGHTER:String = "slargh_fighter"; private static const ENEMIES_PER_WAVE:int = 15;
Public Functions / Private Functions
Usually I stick to the "Urbansquall" convention on this however I do not prefix an 'a_' before the parameter names. Sometimes my functions will stray slightly from the "verbNoun" format when parameters are available and instead I will try to complete a sentence with the parameters. In other words I use "verbPreposition(noun)" format:
public function addTo(vector:Vector):void; public function wrapAround(topLeft:Vector,bottomRight:Vector):void; public function dotOf(vector:Vector):Number;
Event Handler Functions
I will treat event handlers slightly different when naming them. I always name them as if they are happening because of an event (hmm...) Which means basically all of them have "on" preceding them.
onScriptLoad(e:Event):void{} onEntityCollision(e:CollisionEvent):void{}
Alright well as far as I can think of those + the urbanSquall link from above are the conventions I stick with. Hopefully you decide to do the same! Also be sure to read: Better Debug Tracing for some tracing conventions that should be followed as well.
(3 votes, average: 5 out of 5)
Loading ...
Christopher (GoPlaySushi) said
am June 1 2008 @ 5:03 pm
Great and interesting post there! I’ve been using some of these techniques myself - got so sick and tired of not understanding what all those functions and variables did. Espically I love the real-time-verbNoun-thing of which you speek - tend to use that one alot - it explains alot and doesn’t demand long terms. Thanks for an interesting read.
Christopher of GOPLAYSUSHI.COM
Scarybug said
am June 3 2008 @ 8:34 am
Hmm… I never thought of using a convention to distinguish private variables from public ones. I always use caps for constants, especially since in AS2 I don’t have real constants and have to remind myself.
One thing I do is to distinguish function names better from variable names. My variable names are all separated by underscores instead of using camelCase. camelCase is reserved only for functions in my code. This is especially useful to me because I often pass or manipulate functions as variables for doing adaptive AI or Genetic Algorithms.
Thanks for the kick in the butt about refraining from overusing getters and senders. I’m going to definitely apply that rule to my current game.
Andrew said
am June 3 2008 @ 12:11 pm
worst of all with sloppy codeing is to use global variable instead of local.
Andrew /
http://www.eminentgames.com
Douglas Thompson said
am June 5 2008 @ 6:41 pm
It’s always important to stick to a certain set of rules when coding, even when writing code on your own. What the particular standards are isn’t quite so important, though, and every individual or team will have their own, unique ones. Urban Squall or whatever definitely seems to have their shit together and would be worth following, but it’s important to consider alternatives as well, and follow your own nose.
For example, the Hungarian notation-like stuff is often discouraged in type-heavy languages like AS3 and whatever else due to its redundant nature. The variable is typed, it’s plainly visible and the compiler checks for it, so why bother? This sort of thing wasn’t so prevalent here, but the “m_” prefix is generally discarded for the same reason (you’ve got access to the this pointer, so just use that).
At any rate, the getters/setters thing is a little bit of a pandora’s box.
First, I understand that there’s a small performance hit for function calls, as well as parameter stacking/unstacking, etc, but you might want to back up your “20-30fps loss” claim with an example or something, as it seems a little ridiculous to me.
You maybe have a point with the vector class, but it’s a REAL rare exception that should not by any means be the rule. Vector classes tend to be very static, straightforward and frequently called, as mentioned. Generally, you should put off something as drastic as making variables completely public *until* it actually becomes an issue, not just because “it might, possibly, someday have a subtle impact on something somewhere”. Pulling variables out into your public permissions can have some major implications design-wise, which is why the whole concept of a ‘getter’ and ’setter’ exists in the first place, and leads to a very fragile design.
Having said that, the concept of a getter/setter is an ugly one, imo. This article is very rantish and flamebaitish: http://www.javaworld.com/javaworld/jw-09-2003/jw-0905-toolbox.html but the general idea isn’t that uncommon. It’s a bit of a religious war (just look at the comments), but I’m mostly opposed to them, personally. YMMV!
One thing I found really interesting was US’ way of declaring variables readonly. This was something that I REALLY struggled with when getting up and running with AS3. Coming from C++, you have a lot of control over what specifically should be constant. A reference, what it references, what an object’s methods are allowed to do, etc. In AS3, there’s *nothing* and it’s awful. I had initially thought about assigning each “read only” object to a temporary inside a method call to preclude the change, then decided that’d be too much extra work and mess, and the performance issue was there… so I decided to stick a ro_ onto the front of my ‘read only’ variables for a while as well. I finally gave up on that and just don’t do anything now. Probably not the best decision in the world, but it’s good to know that there are actually other people who recognize this issue with the language.
But anyway, thanks for the article/links!
Blah blah blah I’m gonna go make some tacos now.