Commenting

Packages

Packages provide a grouping for related Java classes, interfaces, and other reference types. For example, the Java platform provides many helpful utility classes in the java.util package, input/output classes in the java.io package, networking classes in the java.net package, and lightweight GUI components in the javax.swing package. Using packages is a great way to manage both conceptual and physical complexity. In fact, the package structure of large Java projects is dictated by an application s software architectural organization.

In Java For Artists I will show you how to work with packages. A package structure is simply a directory hierarchy. Related class and interface source-code files are placed in related directories. The ability to create your own package structures will prove invaluable as you attempt larger programming projects.

I will use several package naming conventions to organize the code in this book. For starters, I will place short, simple programs in the default package. By this I mean that the classes belonging to short demonstration programs, with the exception of the code presented in chapters 1 and 2, will reside in the default package. Now I know this is cheating because the default package is specified by the absence of a package declaration statement. If you omit a package declaration statement from your programs, they too will reside in the default package. I do this, honestly, because novice students find the concept of packages very confusing at first. Learning how to create and utilize home-grown packages is a source of frustration that can be safely postponed until students master a few basic Java skills.

I use the following package naming convention for the code presented in chapters 1 and 2:

com.pulpfreepress.jfa.chapter1

An example of this package structure appeared earlier in examples 1.1 and 1.2. For complex projects presented in later chapters I slacked off a bit and shortened the package naming convention to the following:

com.pulpfreepress.

package_name

Both of these package-naming conventions follow Sun s package-naming recommendations. I recommend that you use the following package naming convention for your projects:

lastname.

firstname

.

project_name

So, for example, if you created a project named RobotRat and your name was Rick Miller, the code for your project would reside in the following package structure:

miller.rick.RobotRat

Commenting

The Java programming language provides three different ways to add comments to your source code. Using comments is a great way to add documentation directly to your code, and you can place them anywhere in a source-code file. The javac compiler ignores all three types of comments when it compiles the source code. However, special comments known as javadoc comments can be used by the javadoc tool to create professional-quality source code documentation for your programs. All three types of comments are discussed in detail in this section.

Single-Line Comments

You can add single-line comments to Java programs using the characters // as shown below:

// This is an example of a single-line comment

The compiler ignores everything appearing to the right of the double back slashes up to the end of line.

Multi-Line Comments

Add multi-line comments to Java programs using a combination of /* and */ character sequences as shown here:

1 /* This is an example of a multi-line comment. The compiler ignores 2 * everything appearing between the first slash-asterisk combination 3 * and the next asterisk-slash combination. It is often helpful to end 4 * the multi-line comment with the asterisk-slash sequence aligned to 5 * the left as shown on the

next

line. 6 */

Javadoc Comments

Javadoc comments are special multi-line comments that are processed by javadoc, the Java documentation generator. The javadoc tool automatically creates HTML-formatted application programming interface (API) documentation based on the information gleaned from processing your source files, plus any information contained in javadoc comments.

Javadoc comments begin with the characters /** and end with the characters **/ . Javadoc comments can contain descriptive paragraphs, doc-comment tags, and HTML markup. Example 1.3 shows a file named TestClass.java that contains embedded javadoc comments.

Example 1.3: TestClass.java

1 /********************************************************** 2 TestClass

demonstrates

the use of <b>javadoc</b> comments. 3 @author Rick Miller 4 @version 1.0, 09/20/03 5 **********************************************************/ 6 public class TestClass { 7 8 private int its_value; 9 10 /** 11 * TestClass constructor 12 * @param value An integer value used to set its_value 13 **/ 14 public TestClass(int value){ 15 its_value = value; 16 } 17 18 /** 19 *getValue method 20 * @return integer value of its_value 21 **/ 22 public int getValue(){ 23 return its_value; 24 } 25 26 /** 27 * setValue method 28 * @param value Used to set its_value 29 **/ 30 public void setValue(int value){ 31 its_value = value; 32 } 33 }

Generating Javadoc Example Output

Figure 1-2 shows the javadoc tool being used in the UNIX environment to create API documentation for the TestClass.java file:

Figure 1-3 shows the results of using the javadoc tool to process the TestClass.java file:

image from book
Figure 1-3: javadoc Tool Being Used to Generate TestClass API Documentation

For a complete reference to the javadoc tool and the different doc-comment tags available for use, consult either the java.sun.com web site or the Java in a Nutshell book listed in the references section at the end of this chapter.

Buy on amazon.com >>

Miller R., Kasparian R.

<< Previous page

Table of contents

Next page >>

Flylib.com

Category list

Similar pages

Commenting

Packages

Commenting

Single-Line Comments

Multi-Line Comments

Javadoc Comments

Generating Javadoc Example Output

Similar products