Tag Archives: Convention

Comments and Spacination

This will probably be the last article on style for a while, though there will be more at some point. I’m going to talk about two other aspects of code¬†formatting¬†that are almost as important to me as variable naming: comments and the way you space/tab your code. The latter will now be referred to as “spacination”, although Chrome tells me it’s not a real word. ūüė¶

With the exception of small programs that have run-once use cases, e.g. Project Euler entries, I try to comment all my code. I’ve often heard “if it was hard to write, it should be hard to understand” as justification for leaving code unexplained, however this is in my opinion just shooting yourself in the foot. What if you come back later and need to change something? I always treat my code as if someone else is going to read/use/modify it at some point in time, regardless if that someone is me or not.

I’ve also gotten into the habit of writing Doxygen-compliant comments on all class, method and variable definitions, especially on larger projects. Doxygen is kinda like JavaDoc, in that it generates documentation from comments written directly in the source. It also provides¬†inheritance¬†trees, lists of¬†constructors, members and pretty much everything you’d expect from such a tool. The rules are pretty flexible for creating these types of comments, as you can use either /// or /** ¬†*/ to catch the attention of the Doxygen tool. Some examples:


Regular comments, such as the ones describing the internals of a method, are of course the regular double slash. Even if you don’t use Doxygen, it’s still good practice to comment things. I find it makes for better code in the long run, at least for me.

The next one I’m a bit pickier about. I’m not sure why as I’m not really a neat person in everyday life, but when I write and read code my brain requires it to be spaced out in a very specific way. Maybe it’s because I learned Python first, where indentation was part of the syntax. Either way, I’m very picky about making things line up. There has to be clear levels of indentation, in tabsteps from the left hand margin. I also prefer to have curly braces ({}) on their own line, as opposed to at the end of a function or class definition. Example:¬†

Again, like the variable names, these are just personal preferences and not hard fast rules. I just find these conventions improve the quality and appearance of the code.

T

Advertisements

What’s in a [variable] name?

Lots. As a programmer I learned very quickly that I’m one of those types of people that makes strict conventions and adheres to them whenever possible. Variable naming styles play a huge role in this. Before I delve into detail on my own style, how about a few comments on some of the general variable naming conventions that are out there today?

Variable naming¬†conventions¬†actually have two components to them: the “formatting¬†convention”, and then the actual naming¬†convention¬†itself. The formatting convention mainly deals with how the name is presented, such as the case, any additional¬†punctuation like underscores, etc. The naming portion of the equation is how the programmer selects what to call the variable. Pretty simple.

Formatting is definitely the most straightforward to talk about, as there really isn’t a whole lot you can do in that department. The most popular style seems to be camel case, e.g. “myVariable”, “myByteBuffer” and “someUselessObject.” Camel case is easy on the eyes for variables that are constructed from multiple words, allowing for variablesWithLongerNames to still be readable. It also seems to emphasize the parts of the variable with capitals, which are also generally the more important part, i.e “ByteBuffer” in “myByteBuffer.” The other popular alternative involves the use of underscores to separate parts of the variable. Rewriting the previous variables in this underscore style would give “my_variable”, “my_byte_buffer” and “some_useless_object.” Allow I suppose you could do a hybrid, something like “my_ByteBuffer” or “my_Byte_Buffer”, most people seem to go one way or the other. I’ve also seen underscores prefixed on variables, like “_byteBuffer”. I’m not really sure what this accomplishes though. In fact I personally think the underscores look atrocious, but for the sake of variety will continue to use them for one more paragraph.

On to the names themselves. These can’t really be divided up as easily, as there are lots of different ways to go about the task. One convention I’ve seen pretty often is including a letter or two to indicate type for standard type variables, like “fSpeed”,”bRun”, or “ch_initial.” For arrays and lists it’s¬†uncommon to see “scoreList” or “item_array.” It definitely makes it clear what the variable in question is. Another convention is to include the variables scope in the name. A class member might be named “mTimeStamp”, while a variable passed in as a parameter might be ¬†“p_rate”. There are clearly lots of ways to tackle the problem of names, but as long as the name makes sense in the context is really just a matter of preference.

What about me? Well, as I may have hinted before I’m a big proponent of the camel case style formatting convention. All of my code uses it all of the time, local variables included. I’m also equally picky about my var names. All variables are named based on scope/location, as mentioned above. Global variables get the “g” prefix, members get an “m”, parameters a “p”, enums an “e” and so on. As far as the rest of the variable name goes, I always follow three simple rules:

1. Keep it as short as possible. Make sure that the name is only as long as it has to be in the context that its given. “mTextFileArray” can be shortened to “mFileArray” if it’s used in the “TextFileManager” class, for example.

2. Name it after its purpose. This is the most important rule, in my opinion. Lets say we’ve got a “Weapon” class. The name “mCount” as member variables leaves a lot of questions, as it there are a variety of things that could be counted. “mAmmoCount”, “mClipCount”, or “mFireCount” are much better. Of course, as per rule #1, in the case of “void setAmmoCount( int pCount )” pCount works just fine since the context implies ammo.

3. Name the type if it could be¬†ambiguous. For things like floats/doubles, or ints/shorts/longs this isn’t something I do. Its more in the case of something like “mItems”, where the better option would be “mItemsList” if it’s a linked list, “mItemsPtr” if its a pointer to an array, etc. This rule definitely has more flex to it than the others, and is kinda on a per-case basis.

The bottom line is, I do my best to make sure I don’t have “int temp” or “float testvar” in my code. In situations where I’m trying to pound out a big piece of program quickly I will occasionally let the style go, but this just creates more cleanup work later so I’ve found its best to get it right the first time.

And, by no means are these rules the “right” ones to follow. I’m a self-taught programmer so I probably do some quirky thing, naming conventions included. Like I said before it’s really all a matter of personal preference. Unless you’re doing work for someone else and they enforce code conventions, finding something that works for you is just another part of learning to program.

T


Do you haz teh codes?

Code. It’s a fairly simple word that, in a programming sense, is pretty versatile. Code can act as both a verb (I code, they coded, SkyNet codes…) and a noun (source code). The origin of the word is pretty straightforward too, given what a program looks like and what it does.

It also happens to be one of the words that I feel is most abused. Of course there are several “correct” ways to use code in the programming sense, the aforementioned source code being one of them. However, it seems that that the word is butchered more often that in should be, in ways that for me are pretty irksome. I should make it clear that this is just my opinion. I’m certainly not the authority on language usage by any means. That said, lets begin.

“does any1 here no how to make an mmo code?”

This one is probably the single worst use case that I’ve come across, which is pretty often given that I do admin work over at the indie development site MMORPGMaker.com. I think the problem here is twofold.

Firstly…”an mmo code?” Really? Just one code? I suppose the wording “an mmo codebase” is not too bad in this case, but it still ducks under the fact that treating an MMO, or any game really, as a single unit is not okay. A game needs a rendering layer, some sort of resource and asset manager, input handling, the list goes on. Encapsulating all of these as “an mmo code” seems wrong.

The second issue is more to do with the fact that designing any large scale software project will require a bit more commitment than any of the simple tips for writing “an mmo code” that can be provided by forum users. That’s beyond the scope of this post-rant though, so we’ll move on.

“ya and c++ is the primary code”

This one is almost as bad. Almost. C++ is a language, not a code. Morse is a type of code because it takes things we use, letters, and encodes¬†them into a format that can be transfered easily. ASCII and Unicode are also codes. On the other hand, C++ takes things like words, letters and numbers and allows them to be compiled into something completely different. This something can be used to accomplish a task, play a game, whatever. Maybe our C++ program will even transmit some Morse code over the Internet, who knows. C++ may looks like a secret code if you’re not experienced with using it, but I promise its a language. Unless you’re encoding your entire program in Morse code (I think I’ll try that for the next post), you use a language to write a program.

“I need help doing the codes”

The confusion here is probably because “I need help doing the programming” would be somewhat acceptable. Not as optimal as “I need help with programming”, mind you. I think the biggest problem I have with isn’t the fact that word “code” is used, but the plural on “codes.” We are not working with nuclear launch codes here, unless I’m mistaken. You may write code for a project, but even when talking DRM I prefer the term access “key” or product “key”, as it really is unlocking the program. A program does not have “codes”, it has “source code”. Either way this one’s still got a peculiar sound to it, especially when the spelling is so¬†eloquently¬†expressed as “teh codez.”

I’m sure there are plenty more cases of poor “code” usage, as these were just some quotes I quickly pulled from various programming forums. Maybe I’ve been a little over critical, but it is what it is. Now about that Morse++…

T


%d bloggers like this: