The Importance of Commenting Your Code UNDER REVIEW

I've been a student at Full Sail University for a while now, and one thing I CONSTANTLY see from students, online forums, and programming related forums, is the lack of comments. I cannot count how many times I hear about people going to the creator of said code saying "why is this working?", "how are you doing this?" Sure, it's always nice to google "how to capture motion in a game" or "how to use FMOD" and have all access to open code sources to allow us to do something that may have taken us hours of API documentation reading or a lot of 'head banging against the wall' time. However, are you always going to be able to do that? Is everything you want to do easily written somewhere on the internet? Probably not. A good programmer doesn't need to lookup how to dynamically allocate an array every time he needs one. He should be able to look it up once and fully understand what is going on in the code and how to do it. a good programmer comments as much as necessary. You want people to understand what you're doing, and why you're doing it. So here are some tips on commenting.

1.  Know your audience

Think about who will view your code. Are you on a team? If so, think of the information they need to know to do their part.

// This function pans the camera depending on what the user pressed
// if the user presses A, the camera pans to the left 15 degrees per second, D pans to the right 15 degrees per second

This is for any of the programmers working with the camera. Perhaps making the cinematics.

2.  What purpose does your code provide?

Are you doing this code for your personal use? Maybe your making a program involving Direct2D to reference in any future programs involving Direct2D. In that case, you should use comments to explain why you're using a function or factory. Explain the process so thoroughly that you can look at the program years from now, and be able to recite the steps in your sleep. Is the code to teach beginners? Do the same thing. explain it as if the person reading has no idea what DirectX is. Think of a person who knows nothing of your coding language....keep that guy in your head, and comment, comment, comment.

3.  No such thing as too much commenting

Too much commenting is non-existent! Remember: someone reading that code may not know ANYTHING about programming. Or maybe they just don't know anything about whatever you're doing. If someone specializes in Object-Oriented C++ and he's switching over to C#, he can skip a LOT of basics (but not all) so he may go straight to the advanced stuff. You're thinking "if someone's looking this far into C# then he definitely knows his C#" well think again. Gurus of one language may be ignorant and skip ahead in another language to save time. There is, however, such thing as too little.

This would be an introduction for C++ to those who just got through the basics in an intermediate lesson:

//instead of using int main(void) use int main(int argc, char ** argv)

Now I don't know about you guys, but if I was a noob in programming, I'd think "wtf are two star thingies doing there!?"  A better introduction for replacing the simple main to the more useful main:

// int main(void) is the main function to startup the program you've probably used up until now
// a more optimal version of main would be
//int main(int argc, char ** argv)
// return value: integer (typically 0 indicating success, depends on the program)
// parameters: the integer is the count of arguments(strings) and the second parameter is an array of char pointers (strings)

*Whether you use single line comments or block comments is entirely up to you.*

Was this too much? NO! Was this too little? Perhaps. It largely depends on your audience.  You could, for example, further explain the varieties of the return value? You could also explain what exactly arguments are? Maybe explain what this version of main does that the previous version doesn't?

4.  Format any way you want

Here are some examples of formatting your comments, using a function I made in a word jumble game

string RandomWordGenerator(hTable &hT_Dict)
/*
FUNCTION BLOCKS -> used to explain a function (I like using these, good for custom functions)	
-----------------------------------------------------------------------------------------------------------------------
Purpose: Finds a random word in the dictionary, scrambles it, and uses it in the game
Return: A string that represents the scrambled word
Parameters: a reference to a Hash Table (the dictionary)
-----------------------------------------------------------------------------------------------------------------------
*/
{
	 STEP MARKS -> used to explain the steps to do a particular task (good for anything that takes a lot of steps to do one thing)

	 //step 1:  create a temporary string to hold the word
		  string temp;

	 // step 2: find a random word in the dictionary and set temp equal to the random word
		temp =  hT_Dict->find(randomblahdyblah);

	 // step 3: scramble the word
		 WordScrambler(&temp);

	 // step 4: return the word
		  return temp;
}

There are many different ways you can use your comments. You can make them look pretty or fancy, you can put them in a boring paragraph, you can put them in step format, you can put them anywhere you want any way you want. Best rule of thumb is to put them up somewhere the user will definitely not skip over by accident.

5. Comment ALL your work

Don't be stubborn! Saying "this stuff is so easy, how could I ever forget this?" is just ignorant. My uncle graduated as a programming major. Twenty-two years later as a computer engineer, he saw a new job opening in his company involving C programming that paid a lot more. Unfortunately, spending the years playing with hardware instead of programming software doesn't keep that stuff in your head. He didn't even remember what a virtual function was. Typically if you learned something, no matter how long it has been, you can refresh your memory much quicker than you can imagine! But to his horror....he didn't comment when he was learning about virtual functions. OOPS! Comment ALL your work! I cannot stress this enough. Don't be stubborn and ignore commenting that lesson about the difference between an integer and a short. You may need it one day.

Finally....

6.  Listen to feedback

If someone sends you an email saying "hey, I understand the parameters of your RandomWordGenerator function, but where do you store the string you return? If someone asks you a question, be sure to include something involving that question in your comments. Make your comments so detailed, yet simple, that if your code was viewed by three million people and your email was provided for questions, you would have no unread messages (no, this isn't because nobody loves you, it's because you're comments are flawless).

That's about all I have to say about comment. Please, for your fellow programmers, for your team members, and for yourself, comment your code. I hope you guys do a lot more of it after reading this