File Names and Layout

[Page 815 (continued)] 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 top-level class. Private classes and interfaces associated with a public class can be included in the same file. 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 1999 * 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. Figure A.1 illustrates how a simple Java source file should be formatted and documented. [Page 816] Figure A.1. A sample Java source file. /* * Filename: Example.java * Author: J. Programmer * Date: April, 20 1999 * 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 document at 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 class