Java Introduction Part 2 - Comments

This is the second part on the Java Introduction posts. I would like to discuss in detail the importance of comments in Java development and present the different styles that a programmer can use in order to enrich a program and make it more readable to peers and other programmers.

There are three different ways when it comes to inserting comments into a Java application. These can be categorized as follows:

• End-of-line comments
• Traditional comments
• Javadoc comments

An end-of-line comment begins with two forward slashes ("//") and indicates that the remainder of the line is a comment. The comment terminates at the end of the line on which it appears. A // comment can begin at any point within a line and will continue until the end of that line.

A traditional comment (also called a multiple-line comment) can be spread over several lines. This type of comment begins with a forward slash and an asterisk ("/*") and ends with an asterisk and a forward slash ("*/"). An example is shown below:

/* This is a comment

    the spans over

    several lines */

All text between /* and */ is ignored by the compiler and will not affect the execution of the program.

Java also provides Javadoc comments which begin with a forward slash followed by two asterisks ("/**") and ends with an asterisk and a forward slash ("*/"). Again all Javadoc comments will be ignored by the compiler. Yet the javadoc utility program (which is part of the J2SE Development Kit) will read the Javadoc comments and will be used to prepare a documentation of the program in HTML format.

An example of Javadoc comments is shown below. This example has been take from How to Write Doc Comments for the Javadoc Tool by Sun Microsystems.

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * 
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
 try {
     return getImage(new URL(url, name));
 } catch (MalformedURLException e) {
     return null;
 }
 }

This Javadoc comment will produce the following output which again has been taken from How to Write Doc Comments for the Javadoc Tool by Sun Microsystems.

getImage

public Image getImage(URL url, String name)

Returns an Image object that can then be painted on the screen. The url argument must specify an absolute URL. The name argument is a specifier that is relative to the url argument. This method always returns immediately, whether or not the image exists. When this applet attempts to draw the image on the screen, the data will be loaded. The graphics primitives that draw the image will incrementally paint on the screen.

Parameters:

url - an absolute URL giving the base location of the image

name - the location of the image, relative to the url argument

Returns:

the image at the specified URL

See Also:

Image

 

I cannot stress enough how important comments are to Java programs, and
any programs for that matter. Having worked for a number of years as a
developer I can only say that a bad written program without any
comments is as good as having no program at all. The amount of time
that you will spend in order to understand what a complex Java program
is supposed to be doing and then modify it to enhance it, will make you
appreciate comments as much as I do.