Skip to content Skip to navigation

OpenStax-CNX

You are here: Home » Content » Java comments

Navigation

Recently Viewed

This feature requires Javascript to be enabled.
 

Java comments

Module by: R.G. (Dick) Baldwin. E-mail the author

Summary: This module explains Java comments in a format that is accessible to blind students.

Preface

General

This module is part of a collection of modules designed to make object-oriented programming concepts accessible to blind students.

See http://cnx.org/content/col11349/latest/ for the main page of the collection. If you can see the main page, there is a Table of Contents on the left side of the page. I'm not sure how your screen reader will treat that Table of Contents relative to the other parts of the page.

This module explains Java comments in a format that is accessible to blind students.

Prerequisites

In addition to an Internet connection and a browser, you will need the following tools (as a minimum) to work through the exercises in these modules:

The minimum prerequisites for understanding the material in these modules include:

  • An understanding of algebra.
  • An understanding of all of the material covered in the earlier modules in this collection.

Viewing tip

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.

Figures

Listings

Supplemental material

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 .

Discussion and sample code

Comments

Producing and using a Java program consists of the following steps:

  1. Write the source code.
  2. Compile the source code.
  3. Execute the program.

The source code consists of a set of instructions that will later be presented to a special program called a compiler for the purpose of producing a program that can be executed. In other words, when you write the source code, you are writing instructions that the compiler will use to produce the executable program.

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 the three styles of comments shown in Figure 1 .

Figure 1: Three styles of comments.
Three styles of comments.

/** special documentation comment 
used by the javadoc tool */

/* This is a 
multi-line comment */

//Single-line comment
program code // Another single-line comment

The javadoc tool

The javadoc tool mentioned in Figure 1 is a special program that is used to produce documentation for Java program. 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. Documentation produced using the javadoc program is very useful for on-line or on-screen documentation.

Multi-line comments

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. (A javadoc comment is simply a multi-line comment insofar as the compiler knows. Only the special program named javadoc.exe cares about javadoc comments.)

The multi-line comment style is particularly useful for creating large blocks of information that should be ignored by the compiler. This style can be used to produce a comment consisting of a single line of text as well. However, the single-line comment style discussed in the next section requires less typing.

Single-line comments

Single-line comments begin with // and end at the end of the line. The compiler ignores the // and everything following the slash characters 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 as shown in Figure 1 , or can appear anywhere in the line, including at the end of some valid source code (also shown in Figure 1 ) .

Sample program

The purpose of the program named Comments01 , which is shown in Listing 3 near the end of the module, is to illustrate the use of single and multi-line comments. The program does not contain any javadoc comments.

The commands for a batch file that you can use to compile and run this program are provided in Listing 4 .

When you compile and run the program, the following text should appear on your command-line screen:

Hello World

Interesting code fragments

I will explain this program in fragments, and will explain only those portions of the program that are germane to this module. Don't worry about the other details of the program at this time. You will learn about those details in future modules.

A multi-line comment

Listing 1 , shows a multi-line comment, which consists of three lines of text.

As required, this multi-line comment begins with /* and ends with */. The extra stars on the third line are simply part of the comment.

You will often see 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 shows three single-line comments. Can you spot them? Remember, single-line comments begin with //.

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 
}//End class

One of the comments in Listing 2 starts at the beginning of the line. The other two comments follow some program code.

Run the program

I encourage you to run the program that I presented in this lesson to confirm that you get the same results. 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.

Resources

I will publish a module containing consolidated links to resources on my Connexions web page and will update and add to the list as additional modules in this collection are published.

Complete program listings

Listing 3 contains a complete listing of the program named Comments01 .

Listing 3: The program named Comments01.


/*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 
}//End class

Listing 4 contains the commands for a batch file that can be used to compile and run the program named Comments01 .

Listing 4: Batch file to compile and run the program named Comments01.


echo off
cls

del *.class

javac -cp .; Comments01.java
java -cp .; Comments01

pause

Miscellaneous

This section contains a variety of miscellaneous information.

Note:

Housekeeping material
  • Module name: Java Comments
  • File: Jb1030.htm
  • Revised: 08/19/11
  • Keywords:
    • object-oriented programming
    • accessible
    • accessibility
    • blind
    • Java
    • screen reader
    • refreshable Braille display
    • OOP
    • comment

Note:

Disclaimers:

Financial : Although the Connexions site makes it possible for you to download a PDF file for this module at no charge, and also makes it possible for you to purchase a pre-printed version of the PDF file, you should be aware that some of the HTML elements in this module may not translate well into PDF.

I also want you to know that I receive no financial compensation from the Connexions website even if you purchase the PDF version of the module.

Affiliation : I am a professor of Computer Information Technology at Austin Community College in Austin, TX.

-end-

Content actions

Download module as:

Add module to:

My Favorites (?)

'My Favorites' is a special kind of lens which you can use to bookmark modules and collections. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need an account to use 'My Favorites'.

| A lens I own (?)

Definition of a lens

Lenses

A lens is a custom view of the content in the repository. You can think of it as a fancy kind of list that will let you see content through the eyes of organizations and people you trust.

What is in a lens?

Lens makers point to materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

Who can create a lens?

Any individual member, a community, or a respected organization.

What are tags? tag icon

Tags are descriptors added by lens makers to help label content, attaching a vocabulary that is meaningful in the context of the lens.

| External bookmarks