How to Use Comments in Java Progamming

In Java programming, there is a difference between code written just for machines and code written to be read by people. This first listing is very simple and is meant just for machines.

package org.allyourcode.myfirstproject;
public class MyFirstJavaClass {
  /**
   * @param args
   */
  public static void main(String[] args) {
    javax.swing.JOptionPane.showMessageDialog 
                                   (null, "Hello");
  }
}

This second listing has an enhanced version of the code in the first listing. In addition to all the keywords, identifiers, and punctuation, this second listing has text that’s meant for human beings to read.

/*
 * Listing 5-2 in
 *   "Java For Android Developers For Dummies"
 *
 * Copyright 2013 Wiley Publishing, Inc.
 * All rights reserved.
 */
package org.allyourcode.myfirstproject;
/**
 * MyFirstJavaClass displays a dialog box
 * on the computer screen.
 *
 * @author  Barry Burd
 * @version 1.0 02/02/13
 * @see     java.swing.JOptionPane
 */
public class MyFirstJavaClass {
  /**
   * The starting point of execution.
   *
   * @param args
   *        (Not used.)
   */
  public static void main(String[] args) {
    javax.swing.JOptionPane.showMessageDialog
                                (null, "Hello"); //null?
  }
}

A comment is a special section of text inside a program whose purpose is to help people understand the program. A comment is part of a good program’s documentation.

The Java programming language has three kinds of comments:

  • Traditional comments: Everything between the opening /* and the closing */ is for human eyes only.

    Lines 2–6 in the second listing have extra asterisks (*). They are extra because these asterisks aren’t required when you create a comment. They only make the comment look pretty. They are included in the listing because, for some reason, most Java programmers insist on adding these extra asterisks.

  • End-of-line comments: The text //null? in the second listing is an end-of-line comment — it starts with two slashes and goes to the end of a line of type. Once again, the compiler doesn’t translate the text inside an end-of-line comment.

  • Javadoc comments: A javadoc comment begins with a slash and two asterisks (/**). The second listing has two javadoc comments — one with the text MyFirstJavaClass displays a dialog box . . . and another with the text The starting point. . . .

    A javadoc comment is a special kind of traditional comment: It’s meant to be read by people who never even look at the Java code.

    Wait — that doesn’t make sense. How can you see the javadoc comments in the listing if you never look at the listing?

    Well, with a few points and clicks, you can find all the javadoc comments in the second listing and turn them into a nice-looking web page, as shown in the figure.

    image0.jpg

To make documentation pages for your own code, follow these steps:

  1. Put Javadoc comments in your code.

  2. From the main menu in Eclipse, choose Project→Generate Javadoc.

    As a result, the Javadoc Generation dialog box appears.

  3. In the Javadoc Generation dialog box, select the Eclipse project whose code you want to document.

  4. Still in the Javadoc Generation dialog box, notice the name of the folder in the Destination field.

    The computer puts the newly created documentation pages in that folder. If you prefer a different folder, you can change the folder name in this Destination field.

  5. Click Finish.

    As a result, the computer creates the documentation pages.

If you visit the Destination folder and double-click the new index.html file’s icon, you see your beautiful (and informative) documentation pages.

You can find the documentation pages for Java’s built-in API classes by visiting the Oracle website’s Java SE Documentation at a Glance page. Java’s API contains thousands of classes, so don’t memorize the names of the classes and their methods. Instead, you simply visit these online documentation pages.

  • Add a Comment
  • Print
  • Share
blog comments powered by Disqus
Advertisement

Inside Dummies.com

Dummies.com Sweepstakes

Win $500. Easy.