I really wanted to make this week’s column about good coding practices, but then I remembered having received an email back in January of 2004 that talked about the practices I wanted to discuss. Since I’m famously lazy, here I now bring you the second Mailbag edition of Behind the Veil, though this time the format is one long email, and one long response. Once again, the names have not been changed at all… screw the innocent.
A friend and I came up with the idea to make a turn-based rpg game in java, just to see if we could. of course we started out small with an almost completely text-based design. That sucked, so we (well he, really) came up with a clever way of setting up a 3D dungeon type look (reminiscent of d&d games on nintendo in the old days). Needless to say this took a lot of coding to set up each level, we completed three levels using this model and it looked pretty good. We tried to use a lot of if/then/else statements to keep us from having to write anything twice. It was going well.
We then began working on the code seperately, myself on the navigation system and battle system, he on the inventory system and graphics issues. We had a pretty workable system going for the levels of dungeons which we had coded, the inventory system worked flawlessly, the navigation worked flawlessly (and I don’t think anyone other than a programmer could possibly know how much work it really takes to make the mouse do what you want when you want it to, but that aside), the battle system was passable, but in need of a revamp. Anyway, we both grew weary of the project, after all, we knew there was no commercial value in it, and if you spend 500 or 600 hours working on something, knowing that your only reward is self-gratification it can bring you down.
So the game sat untouched by either of us for a couple of years. He had lost all of his copies of it in a system crash, but I still had both the most recent version as well as a printed copy of the code (which was already in excess of 400 pages, even at this early stage of creation). I decided I would jump back into it full force…then I looked at the code..
Some of the code was commented, some was not. The way this all basically happened was that we exchanged the code through email, the file was quite cumbersome so the comments that we both knew pretty well would get erased. In hindsight, eliminating 50 lines or so of comment didn’t really make the file much smaller, but you know 20/20. So each time one of us added a new feature to it, it would be commented with what was what, what it did, why it did it and what other features it was interacting with. Then the other guy would take the new file, add his new lines to it, email it back with comments, and they would also be deleted. As you read this, I know you think we were fools, and so do both of us at this point.
Anyway, there is an actual point to this. Early on in the creation we lost all of the actual .java code files, and were forced to de-compile the last working copy of the game. What this did was took away the actual comments for each variable, for example: A typical integer (in initialization) would read:
integer xyz; ///this integer identifies a characters current weapon.
So after we lost the comment coding, we simply did not replace it, so in the code now it says ‘integer xyz;’ which really sucks. We lost ALL of the comments on our initialization variables, boolean, integers, even image files. Of course, some are easier to find than others, but as it stands I have been working on the game again off and on for some months now and I still don’t know what a lot of the variables actually do.
One thing that I would like to point out here is that if you are an amateur, like me, and not going to make any money off of your creation you can define your variables way better (without fear of someone stealing your code and selling it, hopefully). We had used simple alpha-numerics for all our variables, a1,a2,a3 and that was what killed it. Had we used variables more like weapon1, weapon2, weapon3 we would have been able to figure out what was what later on. Though, I guess if you are making a game for sale the easier your code is to de-compile, the easier your code is to be hacked or stolen.
I still do this java thing for fun, I still create games (mostly just card games and games based on toys, like “lights out” and “click it”), but they are all heavily commented on. Of course, I am the only one that ever sees the comments, but it sure gives me piece of mind to know that my cribbage applet (which I gave up when I realized that there were 14,658,134,400 different ways that the cards could fall…let me know if you have a shortcut for that by the way), I could open up and start again, knowing why each thing is there and what each one does.
I am still defining variables in that original game, but every time I get another one defined, I think it may be quicker just to start over with the whole damn game…
Learning is painful…
Michael MacMichaelmike Junior III
There are three important coding practices covered in that email. I’m going to briefly touch on each one, and since you’ve already read about the bad things that can happen if you ignore them I won’t harp on that aspect of it. If you’d like a quick refresher before continuing, I touched on parts of this in Column 5.
1) Comment your code. I honestly cannot stress this enough, and spent about fifteen paragraphs of column 5 on this topic. Yes, it’ll take a little longer to write your code, but if you comment as you go then you won’t even notice the difference. Suppose it adds ten hours to the process. If your part of the game has to be completed by someone else, and your code is uncommented, that new person is going to spend ten days figuring out what your code does and adding his own comments in anyway for his own reference. The comments are going to end up in your code one way or the other, it may as well be your hand that puts them there.
2) Use descriptive variable names. If you have a variable being used to control a character’s submersion in water, don’t call it w1, call it waterSubmersion. Commenting your variables so you know what they do is all well and good (it’s called a data dictionary), but if you’re trying to debug your code it’s a lot faster if you only have to glance at the variable names. Sure you could read every single comment to figure out which variable you’re looking for, but it will take ten times as long (yes, I’ve timed it), and when you’re working under a deadline that’s time you simply cannot afford to spend.
3) Back up your source code. At any given time there should be no less than two copies of every line of code, every graphic model, every music and sound file, and every database script. If at all possible, these copies should be in different buildings, so that if one location goes dark the other can immediately pick up the slack. Further, you should burn all your source files to disc at least once a month, in case of a catastrophic system failure.
That seems a little paranoid, right? It is actually vital that you have your source files backed up so that if your hard drive fries, you don’t lose any progress. I can tell you from firsthand experience that it’s not fun having to rewrite ten hours worth of code because it wasn’t properly backed up.
The burns to CD or DVD are required for two reasons. First, so you have a hard, unchanging copy that you can go to if both soft copies become corrupted in some way. Yes you’ll lose your progress back to the point of the burn, but that’s a whole lot better than losing your progress all the way back to the beginning. The second reason is so you can footprint the production process. These hard copies of code in progress will allow you to see how long it takes for each coder to write so many lines of code, and more importantly will let you see how the code has evolved. When the game is finished, you can pull that first disc out so the coders can laugh at the silly mistakes they made early on.
There are many more coding practices, in fact I’m sure there are entire books that have been written on nothing but good coding practices. Covering all of them is beyond the scope of this column, and so for further reading on the topic I humbly direct you toward google.
Disclaimer: Behind the Veil was written by Chris Marks and hosted by Diabloii.net. The opinions expressed in these columns are those of the author, and not necessarily those of Diii.net.