Crash Course
- Comments are ways for you to add text for other people (and yourself) to read that the computer ignores.
- Comments are made by putting two slashes ("//") in front of the text.
- Multi-line comments can also be made by surrounding it with asterisks and slashes like this: /* this is a comment */
Introduction
In this short tutorial, we'll cover the basics of comments. We'll look at what they are, why you should use them, and how to do them (in three different ways).
Unlike many other tutorials on Java, which only briefly mention or outright ignore comments, I've decided to put them front and center, as the second real tutorial in this series—they really are that important.
What is a Comment?
At its core, a comment is text that is put somewhere for a human to read, that the computer ignores.
Why Should I Use Comments?
You should use comments to describe what you are doing, so that when you come back to a piece of code that you wrote after several months (or even just days) you'll know what you were doing.
Writing comments--wait, let me clarify--writing good comments is a part of writing good code. Comments explain tricky sections of code, or explain what things are supposed to do, and is a primary way for a programmer to communicate with another programmer that is looking at their code, who may be on the other side of the world, working for a different company, five years later.
Comments can explain what you are doing, as well as why you are doing it. This helps other programmers (including yourself) know what was going on in your mind at the time.
How to Make Comments in Java
There are three basic ways to make comments in Java. For now, we'll only really consider two of them, because the third applies only to things that we haven't looked at yet, and won't for a little while.
The first way to create a comment is to start a line with two slashes: "//". Anything on the line following the two slashes will be ignored by the computer. In Eclipse (or just about any other IDE) the comments change color (in this case, to green) to indicate that the rest of the line is a comment.
So for example:
// This is a comment, where I can describe what happens next... System.out.println("Hello World!");
Using this same thing, you can also start a comment on the same line as some code, but everything after the two slashes will be ignored.
System.out.println("Hello World!"); // This is also a comment.
A second method for creating comments is to use the slash and asterisk combined, surrounding the comment, like this:
System.out.println("Hi!"); /* This is a comment that ends here... */ System.out.println("More stuff can go after the comment, here.");
This can be used to make multi-line comments like this:
/* This is a multi-line comment.
It spans multiple lines.
Isn't it neat? */
Of course, you can do multi-line comments with the two slashes as well, it just has to be done like this:
// This is a multi-line comment. // It spans multiple lines. // Isn't it neat?
In fact, I think most people prefer using the two slashes all the time, and the slash/asterisk combination is only there because it is a holdover from the C programming language.
There's another type of comment that you can use that is started with a slash, followed by two asterisks ("/**"). This is used for automatically creating technical documentation for your code, but it only really works in certain places, which we haven't really gotten to yet. When we do, I'll describe this style in more detail. (FYI, this kind of comment is called a JavaDoc comment.)
How to Make Good Comments
Commenting your code is easy; making good comments is a little trickier. For starters, you should comment your code soon after you write it, rather than much later. A few days or a weekend away from the code, and you may no longer really remember what you were doing with it. (Trust me, it happens!)
Second, write comments that add value to the code. Here's a bad example of a comment for a line of code:
// Sets the score to 0 score = 0;
Everything the comment says, we already knew. Here's a better example.
//Resets the score to 0, because the game is starting over score = 0;
You don't need a comment for every single line of code, but it is helpful to have one for every section of related code. I would venture a guess that it is possible to "over comment", but the dangers of over-commenting code matter a whole lot less than the dangers of under-commented, or uncommented code significantly.
What's Next?
 |
Having problems with this tutorial? Try the troubleshooting page! |