Learn the proper syntax for javadoc comments, multi-line comments, and single-line comments.
Published: May 31, 2008
By Richard G. Baldwin
Homeschool Programming Notes # 306
This tutorial lesson is part of a continuing series that is designed specifically for teaching computer programming to homeschool students and their parents. Even though the series is designed for homeschool students, everyone is welcome to use the lessons to learn computer programming.
In this lesson, I will explain the proper syntax for three styles of Java comments:
I recommend that you open another copy of this document in a separate browser window and use the following links to easily find and view the figures and listings while you are reading about them.
I recommend that you also study the other lessons in my extensive collection of online programming tutorials. You will find a consolidated index at www.DickBaldwin.com.
Some things should be ignored
Sometimes, when you are writing source code, you would like to include information that may be useful to you, but should be ignored by the compiler. Information of that sort is called comments.
Three styles of comments
Java supports three styles of comments as shown in Figure 1. (Blue boldface was used for emphasis here. Recall, however, that you must never include color in your actual source code.)
Figure 1. Three styles of comments.
/** special documentation comment used by the javadoc tool */ /* This is an ordinary multi-line comment */ program code // Single-line comment |
javadoc
The javadoc tool mentioned in Figure 1 is a special program that is used to produce documentation for Java programs. Comments of this style begin with /** and end with */ as shown in Figure 1. The compiler ignores everything in the source code that begins and ends with this pattern of characters. However, the javadoc tool can search the source code, extract comments of this style, and incorporate those comments in a documentation package describing the program.
Documentation produced using the javadoc program is very useful for on-line or on-screen documentation. However, this is a relatively advanced topic, and it is unlikely that you will see any comments of this style in the sample programs in this series of lessons.
Multi-line comments
Ordinary multi-line comments begin with /* and end with */ as shown in Figure 1. As you have probably already guessed, the compiler also ignores everything in the source code that matches this format.
This style is particularly useful for creating large blocks of information that should be ignored by the compiler. While this style can also be used to produce a comment consisting of a single line of text, the single-line comment style discussed in the next section requires less typing.
Single-line comments
Comments of this style begin with // and end at the end of the line. The compiler ignores the // and everything following it to the end of the line.
This style is particularly useful for inserting short comments throughout the source code. In this case, the // can appear at the beginning of the line, or can appear anywhere in the line, including at the end of some valid source code.
A complete listing of this sample program is provided in Listing 3 near the end of the lesson. You should be able to copy it into a source file named Comments01.java and then compile and execute it. When you do, the following text should appear on your computer screen:
Hello World
Remember, file names in Java are case sensitive.
I have used blue boldface text to emphasize certain aspects of the code in this discussion. Once again, however, you must never include decorations such as color, boldface, or Italics in your actual source code.
A multi-line comment
The first fragment shown in Listing 1 is a multi-line comment. Note that this comment begins with /* and ends with */ (highlighted in blue boldface). The black stars are simply part of the comment. You will often find formats similar to this being used to provide a visual separation between multi-line comments and the other parts of a program.
Listing 1. A multi-line comment.
/*File Comments01.java This is a multi-line comment. *********************************************************/ |
Single-line comments
Listing 2 contains three single-line comments.
Listing 2. Three single-line comments.
class Comments01 {
//This is a single-line comment
public static void main(String[] args){
System.out.println("Hello World");
}//end main - another single-line comment
}//End class - still another single-line comment
|
I highlighted the entire comments in blue boldface in Listing 2 to make them easy to spot. Note that the black "}" characters to the left of the last two comments are not part of the comments. They are part of the program code.
The first of the three comments in Listing 2 begins at the beginning of the line. The other two begin following some program code.
I encourage you to copy the code from Listing 3 into your source-code editor. Compile the code, and execute it. Experiment with the code, making changes, and observing the results of your changes. Make certain that you can explain why your changes behave as they do.
In this lesson, I explained the proper syntax for three styles of Java comments:
In the next lesson, we will deal with the very significant issue of the type of data.
Listing 3. Complete program listing for Comments01.java.
/*File Comments01.java
This is a multi-line comment.
*********************************************************/
class Comments01 {
//This is a single-line comment
public static void main(String[] args){
System.out.println("Hello World");
}//end main - a single-line comment
}//End class - still another single-line comment
|
Copyright 2008, Richard G. Baldwin. Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.
Richard has participated in numerous consulting projects and he frequently provides onsite training at the high-tech companies located in and around Austin, Texas. He is the author of Baldwin's Programming Tutorials, which have gained a worldwide following among experienced and aspiring programmers. He has also published articles in JavaPro magazine.
In addition to his programming expertise, Richard has many years of practical experience in Digital Signal Processing (DSP). His first job after he earned his Bachelor's degree was doing DSP in the Seismic Research Department of Texas Instruments. (TI is still a world leader in DSP.) In the following years, he applied his programming and DSP expertise to other interesting areas including sonar and underwater acoustics.
Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.
-end-