Comment thy Code

[As posted on The Way of the Indie Game Developer]

It has been a while that I wanted to write this post (it was resting in my draft folder for two months now). Even though most of my articles thus far are about game design, managing or generally indie game dev advice, my main role in eNVy softworks is that of the Lead Programmer. So I think it is way past time to share a few things with all the game programmers out there.

If you have been programming for a while I am surely not the first one to tell you this but comments do matter. I will split this post in two parts because it is getting way larger than I expected. The first part will help you understand why you should comment on your code while in the second one I am going to give you some practical advice on how to do it in a way that is easy, practical and will not slow down your progress.

In this point let my clarify that this is advice applicable to all kinds of programming and not only game programming but if I find the need to include an example it will have to do with game code.

Let us start from the basics. What are comments? The Wikipedia definition is way more complicated than it has any right to be so let me give it to you in simpler words. Comments are a chunk of text within a computer program that the compiler ignores. The implementation differs from language to language but their functionality is always the same: a playground of characters you can use in any sense you like!

The most traditional way comments are used is to provide information concerning specific lines of code. You can use them to leave a note to yourself about something you want to change later on or clarifying the function of some obscure line of code.

Enough with the introduction! Why would you want to use comments?

Reason 1: Refactoring

Games tend to be some of the largest programs someone can possibly write, their length spanning from thousands to even millions of lines of codes. Large programs mean a lot of time is needed to finish them. The more you code the better you get and it is a certainty that not too late into development you will be able to improve the code you already wrote (I plan on making a full post on refactoring some time in the future).

So you go back a few months after writing the code to make it better and suddenly you have no idea what you are looking at. This does not apply to all people but most of us will forget how we implemented certain things. Never trust your memory, it will betray you, even if it has only been a few months. Having good comments all over your code will help you make refactoring a lot less painful and by far faster than you would imagine.

Reason 2: Re-usability

A professor of mine told us a story once. He was doing some Operating System (maybe the largest possible piece of software out there) research and came across some code an old student had once written. He tried to find some sense in the code but the complete lack of comments made it absolutely useless to him. He started cursing the student for his incompetence when he realized it was his own code after all. As I said before memory is weak and it can get you in a lot of uncomfortable circumstances.

Even thought every game is unique on its own there are certain universal elements that all games share. When making a new game you probably already have some of the elements you need to make it in an earlier game you made. Why would you code them all over again instead of just taking the old code and change what is needed to make it fit into the new game? If your old code is not properly commented you will find it really hard to even identify what you need to take from it. Revisiting the code for a game you wrote years ago and making it fit into something new is a challenge on itself, imagine how harder it gets if there are no comments around to help you out.

Reason 3: Teamwork

By now you probably know that the majority of video games are made by more than one programmer. Sometimes dozens of programmers work on the same code without even having regular contact with each other. Team programming is a really different story but the main principle behind it is dividing the program into logical chunks and assigning each one of those chunks to a different person, while some other programmers are charged with making those chunks work together. No matter the reason, other people from your team will eventually have to work with your code and, do you know what is harder than understanding a piece of code you haven't seen for years? Understanding a piece of code you have never seen before! You can make everyone's life easier by using comments. Your co-workers will have no problem understanding what you were intending to do and can utilize your code easier and more efficiently.

Reason 4: Debugging

How does commenting helps in debugging you ask? Well weirdly enough it does in a very special way. Most programmers tend to write code on the spot without planning beforehand. That means that they are not always sure where a programming session may take them. This is actually the main cause of most bugs as well. When you comment your code while you write it, you force yourself to think harder on why every line is important. If a certain line of thinking takes you off the right trail commenting while writing the code may as well lead you back on track. On the other hand if you do not change your train of thought while coding and encounter a bug it is easier to find the gap in your logic when you are reading it in a natural language (such as English) rather than in a programming language.

Those may be the main problems that comments solve but comments are not necessarily the only way to solve those problems. Sometimes comments are the best way to convey a message but sometimes simply changing the names of your functions and variables can do the job.

I will tell you more on how to write easy to read code and how to use comments responsibly on the next part of this article; this does not mean that my next article will necessarily be the second part of this one or that it will be delivered soon.

I hope you enjoyed this read, share it if you did and tell me your own views and opinions below.

If you would like to learn more on a specific subject feel free to leave a comment and I will try to help you the best I can. Have a nice day and stay focused!