I’ve seen a lot of poorly written and ugly looking code in my time. That’s not even considering the undocumented and uncommented code. We all know we should comment our code but how many of us do it consistently? I admit, when I’m in a coding frenzy, stopping to write comments just gets in the way of my thought process and can be distracting. I will however write a bunch of comments before I write the code, of the operations I think I need, in order to give me an outline of where I need to get to. For example:
// Get URL string for video file
// Load video file from URL request
// Load video file into video player
// Set up video player
// Play video
I may not know all the APIs to load and play the video just yet, but at least I’ve given myself an outline and as I fill in the code below each comment, I can see exactly what I’m doing and where I need to go.
Why Your Code Sucks
The point of this article is not to talk about comments, but how to avoid writing them in the first place within your functions and still be clear for everyone else, for the most part. This is your code:
newPlPt = crt2pl( nmc.x, nmc.y );
Not even a comment could concisely convey the meaning of that hideous statement. Instead, why not:
newPolarPoint = cartesianToPolar( newMediaContext.x, newMediaContext.y );
Well written code is self documenting. Let me restate that: if you can write code so that someone can jump to any point of that code and understand what’s going on at that point, read it like a sentence, and not have to decipher minute details like what each variable means, then you don’t have to comment most of your code.
There’s no reason you need to shorten the names in your code. Most programmers have never had file size limitations to deal with, so there’s no reason for it. Stop pretending you live in the 1960s and embrace nearly infinite file storage. To save keystrokes perhaps? Please, use a real IDE with code completion and stop doing stupid things like:
public function updateP( p:Player, d:MovieClip, b:MovieClip, t:Textfield);
Function Names
Also, because your functions are essentially actions, they need to reflect that in the name, so put a verb in the beginning of your function such as: getData(), setStatus(), enableWiFi(), hideControls(), handleGraphicException(), launchBall(), etc.
Class Variables
Get rid of the underscores in front of your class variables. For example: _dg; _myNumber;. All class variables should be private anyway, so why do you need that ridiculous convention? It’s a hold over from C where there was no “private” keyword, so you’re using it and you have no idea why.
Also, what’s with the “my” naming convention? You sound stupid when you have those: myInstanceName, myMovieClip, myGraphicsContext. Of course it’s yours, whose would it be, if not yours? If you’re programming with a colleague, do you refer to his variable references as yourInstanceName? Or hisVideoFileURL? Of course not. Don’t be that stupid; you’re reading too many stupid online tutorials by uncreative people who only code because they have nothing else better to do while living in their parent’s basement.
In the very least, be consistent with your naming conventions.
Hungarian vs. Polish notation
Depending on which language you’re coding in, you may need to use a notation to help you with type casting. Let me rephrase that: if you’re using a loosely typed language, use Hungarian notation. You should probably use this with strongly typed languages anyway because with abstract types, you never know what you could get into and it’s just generally less confusing.
Hungarian Notation: vendorNameTextField or vendorName_txt
Polish Notation: txtVendorName or textFieldVendorName
Why not Polish notation? Not only is it ugly, but why would I sort on variable type instead of the variable name like I can do in Hungarian notation? The notation names come from how the speakers of those languages modify their verbs and nouns. To say: “My ball” in Hungarian is: ”labdám” where “labda” is the root word and the ‘m’ singifies a first person possessive. Hence the ending of the word shows the crucial information. It’s the opposite in Polish notation where the beginning of the word is modified. In the interest of full disclosure, I love the Polish, but I am Hungarian, but I promise that’s not why I prefer one over the other.
Final Thoughts
In the end, be consistent, be clear and spell out your variable and function names.
