Naming Conventions – Why Your Code Sucks
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.
Haha, great post!
Great article! Although, the SEO compatible URL looks like a weird sex act… 😉
Haha, Hungarian notation prefixes with type/intended use!
Why your column sucks.
Well, actually overall it doesn’t. But you are a bit on the dogmatic side. If something is the right tool or technique for the job, you use it. Don’t use something else because you took a blood oath NEVER to use * Recently I worked in Lua, in a game related environment. You had a meg or two total for graphics, sound, and code. It goes very quickly. Brevity in variable and function names was a necessity. On the subject of naming conventions, if it works for you and anyone else you work with, it’s good. All class variables should be private? Encapsulation has it’s advantages. But if you are working in a graphics intensive environment, you may sweat every cycle. How much time you spend going through functions to get at variables only your profiler knows for sure. But if speed is critical, perhaps you should have direct access. Drifting back to my core point, it’s good to have guidelines. But never say never. Use the right tool for the job.
I always appreciate people willing to disagree with me! You’re right about that SDK that uses Lua. Out of curiousity, which one was that? I’ve programmed a game in Lua, so I know the language, and I suppose what you’re saying is, because it’s not compiled and instead included with the app, the character count in the code matters. I’m not sure why you’d have that kind of restriction these days, so I’m curious.
Also, I believe you’re talking about the overhead of referencing and retrieving variables from encapsulated classes. If performance matters to you, there are ways to speed that up. One is to simply get a pointer to the object and store it locally, and another is to copy the data to a local variable and pass back the value when you’re done.
OOP does have a slight overhead in exchange for better maintainability in your code. However, it doesn’t matter how fast your code is if it’s not maintainable or buggy. But there are plenty of software engineering concepts you can use to speed up your code without making it ugly and unmaintainable.
When you program in a large team, they all have coding practices that you must follow. This is nothing new, this is just my way of doing things for people who haven’t been exposed to these concepts. So feel free to disagree, but each guideline is explained on why I use those methods.