Saturday, August 11, 2012

Take a Note

Looking at my code, I've come to realize that, more often than not, I have more comments and documentation than I have actual code. This is great for so many reasons.

First, when working alone on a project, its easy to get lost in your oceans of code and forget why you did something a certain way. The Glow currently has 22 C# files, along with dozens of prefab objects, textures, etc. And that's just the tip of the ice berg. Having this trail of bread crumbs helps me keep track of everything without having to pour over a hundred lines of code to figure out what's going on.

Second, if, by some miracle, I manage to get help from another programmer, it won't take them a week to figure out my code. I've been accused (more than once) of writing spaghetti syntax. If I hope to ever have someone lend a hand with this game, they will need to be able to quickly see how my code works.
 
//what was I thinking?
 Now! HOW do I keep everything so well commented? This was actually a big issue for me back in my early days of scripting. I just dove into the code and started writing. I would then find myself going back over my code and trying to squeeze in comments to explain how things worked. Not only was this a giant pain in the ass, but I rarely covered everything and often couldn't even remember why I did things a certain way.
 
Now, however, in an unfamiliar language and working on a much larger project, I've had to take a different approach. I begin with my comments. I'll write the name of a function, but it won't actually do anything. It's empty!

What the function does contain is a commented list of all the things its going to do, written in the order that it will do them. As I move forward then, I simply write the code between these comments. This helps me so much when planning out my code, and helps even more later on when going back to reference those functions.

So! My advice for the day; plan things out by writing them down directly in your code. Don't wait until after a function is complete to document it. This will turn all your crazy "for" loops, switch-cases and function calls into simple A, B, C steps. (And others will be impressed by your detailed documentation later on.)

No comments:

Post a Comment