Tag Archives: Programming Style

Graphviz and Doxygen

About once a week or so I run my entire GL Engine project through the Doxygen documentation generator to check that I haven’t missed any documentation and get an idea of how my project is shaping up. There’s an option to use a package called Graphviz for the inheritance/file graph documentation, although up until today I’d never paid much attention to it. On today’s doc run I decided to install it and see what it could do. It turns out it can do a lot.

Graphviz generates all of the inheritance diagrams in the same way as Doxygen’s internal tools, but with a bit more style. Example from GLVertexBuffer:

One of the cool features exclusively supported by Graphviz is the “Collaboration Diagram”, which essentially shows all of the classes that are involved with a particular class. This includes the inheritance tree, and any members that are also instances of classes included in the project. A simple case is the VertexPNT class:

Purple arrows mean “has a member variable of type”, while blue arrows show inheritance. A more complex one for the SkyObject class:

Another feature of Graphviz that I can see myself using very often during development is the file linkage tree, which shows which shows how files are related to each other through #includes. Here’s one for my Vector3F class:

Click for bigger, although be warned that it’s over 4,000 pixels wide. 😉

There are also a few other useful features, such as call/caller graphs for each method. I’m definitely going to be checking “Yes” on all of these options on my subsequent doc generations. I can already think of a few cases where they’ll helpful for development. Ensuring that all code only references the platform agnostic classes, e.g. VertexBuffers instead of GLVertexBuffers, is a big one for me. And of course, at the very least they’re pretty cool to look at.

T

Advertisements

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


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


%d bloggers like this: