In this video, we're going to talk about comments in source code.
Now comments apply to just about every programming language out there.
C++ has two kinds of comments. But before we talk about those comments,
let's talk about what comments are in general.
Comments are programmer readable explanations in the source code.
Explanations, notes, annotations,
anything that adds meaning to what the program is doing.
One thing that's very important to understand is that
the comments never make it to the compiler.
In c++, the preprocessor strips out the comments so that the
compiler never sees them.
It may sound kind of weird right we're writing something that the compiler is never going to see.
That's the whole point. This is human readable.
This is for the next programmer that's coming down the pipe or
for yourself when you have to go back and modify code.
You can leave comments in the code explaining what you did and
why you did. C++ has two styles of comments. The first one is
just a single line comment and I'll show you what that looks like.
It's basically two forward slashes side by side
and then everything after that until the end of the line will be ignored.
So this is a comment
and the compiler will never see that comment.
That's only for your eyes only or for the eyes of programmers coming after you.
So that's a single line comment.
Typically, you see these comments done like this or you may see them for example here,
right after this variable declaration here for favorite number.
We could do something like //. This is where
my favorite number is stored or something like that.
That's kind of a silly comment, and I'll talk more about
using these things wisely.
The compiler is never going to see this because the preprocessor
will see the comment and strip it out and just replace it with a single space.
Okay. So that's one style of comment. That's a single line comment.
The other kind of comment is a multi-line comment.
And that's a /, again a forward slash followed by an asterisk
and then an asterisk followed by a forward slash.
So everything between those two elements is a comment and will be ignored.
So this could be --
this one spreads across lines, so this could be a multiple line
comment, like that.
Do anything you like. And again, it's totally free form.
You can make it look however you want you could indent you could do anything you want here.
Everything in here will be ignored.
Okay. So now let's talk a little bit more about these comments and
what makes sense, what doesn't make sense.
The idea behind programming is literate programming.
Basically, your code should be self-documenting.
Does that mean we don't write comments? Well, no. So you want to be sure that what you write
makes sense. In this case,
here's my code. Here's my main and that's the block of code that I've written.
This is pretty self-explanatory. I mean, I'll leave this comment in here I'll
fix that typo here.
But there's an integer called favorite number.
You're outputting
to the console enter a number you're reading from the console and you're printing out some stuff.
This code doesn't need any commenting. It's very, very clear what it's doing.
That's not always the case. Sometimes code is very complicated.
It's using some complex algorithms.
Maybe you're using some really clever efficiency
tweak to make it run faster, but it makes it less obvious what it's doing.
Those are good examples of where you should use comments.
Don't comment the obvious. For example, right here,
you don't want to say return zero.
That's silly. I mean I know I want to return zero i just set it in the code.
So those kinds of comments you really don't want to use
also if you're adding a and b you don't want to put a comment that says
you know adding a and b, it's pretty obvious from a plus b what you're doing.
So you really want to explain more complicated code.
You also want to keep the style of the comments consistent.
So for example,
I will have this line comment here which goes toward the end of the line.
Over here, I really don't want to do the other style comment
and do something like that. You want to keep your style consistent.
Now the multi-line comments are often seen at the top of files.
So I'll do this, and
in this case CodeLite kind of helps me out a little bit,
but I'll do that. So many times, you'll see code that looks like this.
You'll see a bunch of asterisks on top and then you'll see a bunch of asterisks down here,
creating like a little header block.
Now notice, I've got a beginning comment here and the end of the comment here.
Everything in here will be ignored, but in here you'll see stuff like author,
and I'll say Frank, dates things like that
copyrights license information. A lot of that is very commonly seen
in a multi-line comment at the top of the source file.
Another good example of a good comment would be suppose that inside this function
I'm doing some kind of algorithm and I've tweaked the algorithm.
So I could do something like using
a modified
version of Dijkstra's algorithm, let's say,
to improve space efficiency or anything,
something like that.
Now the programmer coming after you understands that you're using Dijkstra's algorithm
and you've modified it somewhat.
Dijkstra's algorithm is a very well understood algorithm.
So you've tweaked it somehow to improve space efficiency.
Maybe in the body of that algorithm, you can comment what exactly you've done.
Okay. So that's an example of a good comment. So again, don't comment the obvious.
Good commenting doesn't justify bad code obviously.
You don't want to write really bad code and then put a good comment in there saying something silly.
One of the dangers with comments is that many times
programmers use comments as version control.
So up here, you'll see something like,
let's say, 11/11/2017.
And you'll see something like Frank fixed bug
in something.
And then another programmer will come across 11/13/2017.
Maybe it's Joe, and Joe added
function to do something.
That's not a good idea.
If you want to use versioning use version control. Use something like subversion or git,
don't write your versioning here.
The problem with this is some programmers will do it some programmers won't.
And this really won't be reflective of all the changes that actually occurred in the file.
Okay. So again don't - you don't do this this is not a good idea.
Use a real version control system.
Finally, if you go back and modify code,
make sure you look at the comments and modify the comments if necessary.
There's nothing worse than a programmer looking at some code and seeing
a comment that looks like this.
And then you look at the code, and it doesn't look anything like Dijkstra's because
another programmer changed it to something else and didn't change the comment.
So it's real important that you keep your comments and your code in sync
as you go along.
Okay. That's pretty much it for comments. In the next video,
we'll talk about the main function itself, and talk a little bit about what's going on there.
s