Readability: Comments

In this video we're going to talk about comments which are used for documenting and for disabling parts of your code. Now the most important function of comments probably is for documentation. That is, adding pieces of code that do not execute. But they can be read by other human beings to understand what's going on in your program. These come in two styles in Javascript. One is the line comment, which starts with two slash characters and then anything after that does not execute.

These can be at the beginning of the line or anywhere else on the line. So if you wanted to document one of these lines in this file, you could just add two slashes here and say this is the month. That's not exactly a helpful comment. It's clear enough from the assignment what it's doing. But this does work. Now the other function of a JavaScript comment is to disable parts. So if I want say, this line, not to execute anymore and I only wanted to find year month and holiday. If I put the comment here, now this line no longer does anything. So, let's copy this and switch over to a JavaScript console and execute this. So year is defined month is defined.

And holiday is defined. But day is not. We get a reference error, because it's commented out. So when you're working through your code and fixing things, being able to comment bits out, so that only certain portions execute, is a really handy thing to be able to do. We'll bring this back in. So that's line comments. There's one more style of comment that you can use in JavaScript, and that's called a Block Comment. It starts with a slash followed by an asterisk and then you can write comments, across multiple lines. Finally ending with an asterisk and another slash like that. You'll see these all the time in JavaScript for inserting long paragraphs or just other elements where a lot of text is needed in one place, and maybe it would get a bit tedious to put the double slashes in front of every single line. Now, you can see that these will break across lines, so you can use this to disable parts of your code as well.

So. I can do this. And I'm doing all this incidentally in my Text Editor because it has this syntax highlighting which makes it very clear what's happening. So right now, this is all commented all the way to the end and it won't stop until I put the second asterisk with the second slash in there. So now these three lines are commented out so the only property of this object that will be defined is holiday. I can undo this. So one note about this. Block comments are really useful and you'll see them all the time. But you need to be careful with these because every once in a while a character like this will appear as something that's actually legitimately not a comment so Douglas Crockford for example recommends never using block comments. That might be overdoing it a little bit and you'll certainly see them a lot. You just need to be careful about using block comments inside of a bunch of active code.

They're mostly useful for documentation and I think it's probably a good idea to avoid them inside a block of active code, sticking mostly to line comments in that case. But I want to show you a large JavaScript file with a lot of documentation in it. This is JQuery, which we'll be looking at later in this course. But you can see the version of it that hasn't been optimized for bandwidth is loaded with comments starting with a big block comment at the top and then many, many line comments. And as you scroll down you can see that nearly every useful block is documented with a comment.

This makes it very nice, and makes it a lot easier to understand what's going on. Now, jQuery is a large JavaScript library. There is a lot going on here. So no amount of comments is going to just make it perfectly clear the first time you read through it. You still have to do a lot of reading and actually read the code and understand it, but having these comments in here is a huge, huge help. And I really can't recommend enough making sure that, even if you're the only person that you ever expect to read the code, add lots of comments, because it will always help you. It's just a little bit of extra effort, and it can pay off huge if you set your code aside for a couple of days or a couple of weeks, a couple of months, even.

To be able to come back and have something to read other than the code itself that tells you what your intentions were is really useful. So, that is a look at comments in JavaScript, and what they do, which is allowing you to document your code for your own readability, and to disable portions of it, which can be helpful in debugging.