Skip to main content

Section A.5 File Names and Layout

Java source files should have the .java suffix, and Java bytecode files should have the .class suffix.

A Java source file can only contain a single public class. Private classes and interfaces associated with a public class can be included in the same file.

Subsection A.5.1 Source File Organization Layout

All source files should begin with a comment block that contains important identifying information about the program, such as the name of the file, author, date, copyright information, and a brief description of the classes in the file. In the professional software world, the details of this “boilerplate” comment will vary from one software house to another. For the purposes of an academic computing course, the following type of comment block would be appropriate:

/*
 * Filename: Example.java
 * Author: J. Programmer
 * Date:  April, 20 2022
 * Description: This program illustrates basic
 *  coding conventions.
 */

The beginning comment block should be followed by any package and import statements used by the program:

package java.mypackage;
import java.awt.*;

The package statement should only be used if the code in the file belongs to the package. None of the examples in this book use the package statement. The import statement allows you to use abbreviated names to refer to the library classes used in your program. For example, in a program that imports java.awt.* we can refer to the java.awt.Button class as simply Button. If the import statement were omitted, we would have to use the fully qualified name.

The import statements should be followed by the class definitions contained in the file. Listing A.5.1 illustrates how a simple Java source file should be formatted and documented.

/*
 * Filename: Example.java
 * Author: J. Programmer
 * Date:  April, 20 2022
 * Description: This program illustrates basic
 *     coding conventions.
 */
import java.awt.*;
/**
 * The Example class is an example of a simple class definition.
 * @author J. Programmer
 */
public class Example {
  /** Doc comment for instance variable, var1 */
  public int var1;
  /**
   * Constructor method documentation comment describes
   *   what the constructor does.
   */
  public Example () {
   // ... method implementation goes here
  }
  /**
   *  An instanceMethod() documentation comment describes
   *   what the method does.
   *  @param N is a parameter than ....
   *  @return This method returns blah blah
   */
  public int instanceMethod( int N ) {
   // ... method implementation goes here}
  }
} // Example
Listing A.5.1. A sample Java source file with javadoc comments.
You have attempted of activities on this page.