Lesson No 5: Comments in C programming

This will be a shorter lesson, I think most of what we will talk about is how to use comments in code, where they should be used, etc. because comments can be summed up in about 2 sentences, it's honestly the easiest concept in programming.

Comments in C programming

What is a Comment and How Do You Use One?

Comments In C Programming

Alright, so a comment is just what it sounds like, it's a comment you can place in the middle of your code. There are two ways to write a comment, one for a single line comment, and one for multiple lines:

//This is a comment that has to be on one line

/*This is a comment that can be on

multiple

lines*/

                         

Notice the obvious differences, the one that is on a single line is written as a double forward slash followed by the text you wish to have in the comment, and the one on multiple lines has a forward slash and an asterisk (star), then, when the comment is done, there is a closing asterisk and a forward slash, very simillar to how curly braces work for the main function. Comments are unqiue in that when the compiler goes through to compile your code, it removes all comments and white space in your program, so in essence a comment is a bit of code that the compiler is told to ignore. Alright, as far as how to write a comment, that's it. Next I want to cover briefly where to use comments and when to use them, because theres nothing worse than a programmer who doesn't get the difference.

Comments, why they are important and how to use them

At this point the code we've written is short, to the point, and hopefully by now somewhat self expnaitory. In the future, you will be designing real software which can be immensely conplicated and have lots of moving parts. Let's say you write a game, and in the game you have a goal of writing an animation system. This is a very complex task even for a very primitive 2D game, and it involes lots of functions, calls to different libraries, etc. As you are writing your code many times you will notice you need to make a small function to handle certain things for you, then combine those functions together in a specific way to actually animate a sprite. This can sometimes get to be several hundred or even thousands of lines of code depending on how complex the task is, that's a thousand lines of variables being created, functions being called, functions being written, etc. Imagine if you had absolutely no explanation in the code on how any of it worked, and anytime you had a question you had to go ask somebody how it worked, or buy a book and look up references to each thing in the code. That would be AGONIZING, that's where comments come in. Comments are essentially small notes you can leave for people reading your code, and believe me when I say you will eventually write such sprawling (often times hideous) bits of code that you will need to have comments, I mean if you're coming into work writing hundreds up to thousands of lines of code a day thinking about all of these things working together in very intricate ways you are going to start losing track of what each thing in your code does, so comments are every bit as important to you as they are for others.

Examples of Good Comments

Everything in programming has a good and a bad, and comments certainly are no different. Comments can be great tools for explaining complex code to somebody, they can also become messy and make code harder to read. The goal of a comment is to make the code easier to read, given a decent software developer you can generally look at code and given enough time figure out what it does without comments, but comments are there to make this process quicker. That said, bad comments clutter up code, explain obvious portions of code, and just make everything harder to read. My style is I tend to use a single line comment until the comment is 3 lines long, and then I switch to a multi-line comment.

Can I Write No Comments?

If you want to be the most hated person at your job, go for it. Let me show you an example from that game I wrote, I'll remove all of the comments, and add them backafterwards.
Before comments:  After comments:  Now again, to be fair, not only is audio code some of the most annoying code to write, but it's also way beyond what most of you probably understand even just as far as how a computer works as far as reading data and using that to play audio so with comments probably didn't look a lot better, but you could somewhat make out what each thing sort of was. Without comments, you couldn't even begin to decypher what MAY have been going on. I think this should in and of itself explain why comments should be in your code. The only thing worse than someone who writes too many comments, is somebody who doesn't write them at all.

Conclusion

Hopefully you now understand comments, where and how to use them, and why they are needed. If nothing else, at least you got to see some interesting looking code? Like I said, this was a shorter section, and most of it was just filler to make up for the fact that comments aren't really that hard to understand, but everything I said, though not required knowledge, is extremely important, so try to remember it. In the next lesson, I want to take a look at writing a very basic function, that way functions don't seem so mysterious anymore, afterall C is a functional language so the quicker earlier you understand functions the quicker you will understand how C programming works in general.