Welcome to the first of the blog posts relating to our second P in the list, Programming!

Comments

Today I’m going to be talking about commenting code. Something I was first introduced to back in the 80’s with the Rem command on my ZX Spectrum. My commenting back then though was limited to a small asterisked box at the top containing the name of the project and my name, and then the occasional comment at the top of a section labelling it as the “movement bit” or the “game over bit”.

Now as with GDD’s there are those out there who advocate for commentless code, saying that if the code is well written that comments are un-necessary. And while this is perhaps true to a degree, I find it quicker to read a commented description of what a function does rather than having to read through the code to discover it.

That being said, comments can sometimes be used to explain bad code rather than rewriting the bad code into something better. Which isn’t an ideal practice.

And even worse are bad comments. I’m guilty of writing some of these myself, especially late at night after a beer or two. I’m sure you’ve all seen comments like “This is the bit that does the thing”. Comments like this are a complete waste of time and definitely should be avoided.

Writing useful comments

I find comments to be exceedingly helpful, especially when I’m returning to a project which I haven’t touched for a while. When you’re working in a team comments can easily inform a team member what code does, or how.

So, how to write good comments? The first piece of advice I can give you is to make your comments clear and concise. Don’t assume the person reading the comments has any idea of how the code works so please avoid using ambiguous terms in them.

Try to keep comments brief. Apart from a comment block at the start of a script file which can be any length really without disrupting someone trying to read the code. Even for a function description there is no real reason to use more than two or three lines of comments.

When it comes to commenting source files, I always try and include a header comment block which gives details like what project it’s from, what the file contains, and in the case of the main source file, a revision history. As I said earlier, it doesn’t matter so much about the length of this first comment block as it doesn’t interfere too much with reading the code. But obviously don’t write the comment equivalent of Tolstoy’s War and Peace.

Another thing I find really helpful to comment is variables. I usually leave a single line comment above the variable declaration describing what the variable keeps track of, I find this combined with a fairly clear variable works well.

//	Sets the players initial velocity
player.yVelocity#=0.0

I also add a comment block to the top of every function definition. This contains the usage details of the function, as well as a couple of lines of description.

//********************************************************************************
//	null = UpdateZones( speed# as float)
//********************************************************************************
//	This function updates the positions of the zone sprites and maintains the 
//	distance variable
//********************************************************************************

As for the rest of my code, I certainly don’t comment every line as some code is so obvious that it’s not necessary. Instead I add a title comment at the start of a particular bit of code, be it in a loop, or a function, or wherever, and then a comment which breaks down what the next few lines are doing.

//	Creates the sprite and sets the properties
bgLayers[layerID].spriteID[0]=CreateSprite(imgID)
SetSpritePosition(bgLayers[layerID].spriteID[0] , 0 , 0)
SetSpriteSize(bgLayers[layerID].spriteID[0] , width# , height#)

Practice makes perfect

When it comes to commenting, there is no better way to get experience than actually writing some. Just remember to keep them concise and useful. There is no better feeling than returning to some code after a break and be able to just pick it up where you left off thanks to the brilliant comments you’d left 🙂