The objectives of this section are as follows :
In general, the source code should be self-documenting . The code should read like a book, where comments act as footnotes when a deeper explanation is needed. The format of the source code should follow a structured coding standard. All source files in the project should appear as if the same person wrote them. This makes software maintenance much easier. The coding standard should be well structured to allow the logic and flow to be easily identifiable. Lastly, identifier names should be written using English words. Note More information on coding standards is provided in the "Formatting" section later in this chapter. Naming rulesNaming rules standardize the look and readability of the source code. The rules described in Table 4.1 provide a good starting point for most projects. Table 4.1. The Naming Rules for Java Identifiers
FormattingFormatting rules help standardize the layout of the source code. The following rules are sufficient for most projects:
Comments and DocumentationComments provide a mechanism to convey information about a program that cannot be done using the Java programming language. Ideally, comment usage should fall into the following five distinct categories:
Using Javadoc CommentsJavadoc comments consist of special delimiters and tags that when placed in source code can be used by the Javadoc utility to generate HTML pages describing classes, inner classes, interfaces, constructors, methods, and fields. That is, Javadoc enables you to create user documentation from source code comments. The generated HTML pages are available to other programmers on the project. Javadoc comments promote good communication between programmers and their usage is strongly recommended. Note More information on Javadoc can be found at http://java.sun.com/j2se/javadoc/. Javadoc comments begin with a delimiter , /** and end with another delimiter, */ . The lines between these two delimiters consist of a description of the element and special tags that direct the Javadoc utility how to format the output. Because the generated output consists of HTML text, you are allowed to include HTML tags. The general form of Javadoc comments is given in Listing 4.3. Listing 4.3 General Form for Javadoc Comments/** * Description * * @tag comment for the tag */ You should consider using the following Javadoc guidelines:
Listing 4.4 General Form for Class or Interface Javadoc Comments/** * * Descripion of class or interface * * @author Name of author. There can be multiple author lines. * @version Version and date string. Use the source code control's version number. * @see reference (you must have access to source code) */ Listing 4.5 General Form for Inner Class, Inner Interface, or Variable Javadoc Comments/** * * Descripion of inner class, inner interface, or variable. */ Listing 4.6 General Form for Non-private Methods Javadoc Comments/** * * Descripion of method * * @param param1 Description of first parameter. * @param param2 Description of second parameter. * @param paramn Description of nth parameter. * @return Description of return value. * @throws Exception class name. Conditions when exception is thrown. */ Java Source File LayoutThe program layout is the pattern for how source code files should be constructed . Source code files should be based on a coding template. A sample template is presented in Listing 4.7. The following elements are listed in the order they appear in the template file:
Note Import statements are ordered from general to specific as shown in the template in Listing 4.7. Also, only import the specific classes that are used by the application; avoid importing * from a package.
Note Classes, interfaces, variables, and methods are further ordered according to their access modifier. Public identifiers are listed first, followed by protected, package, and then private.
Listing 4.7 Template for Program Structure/* * SourceTemplate.java * * Copyright 2000-2001 ThisCompany, Inc. * All rights reserved. * * This software is the confidential and proprietary information * of ThisCompany, Inc. ("Confidential Information"). You * shall not disclose such Confidential Information and shall use * it only in accordance with the terms of the license agreement * you entered into with ThisCompany. */ //package name package thiscompany.thisproject.thisapplication; //import java package //import javax package //import product API packages //import company API packages //import project specific API packages //import application specific API packages /** * * This sample source header file describes the structural layout of all Java * programs. You can include HTML within this section. In particular, * common use is made of * <i>italic</i> * <code> monospaced font for code</code> * <pre>display text how it appears, with spaces, line breaks, and so on</pre> * <b>boldface<b> <p> - empty paragraphs for spacing * * @author Joe Programmer * @version %I% %G% * @see Collection * @see Collections# sort * */ public class SourceTemplate { //Constants public static final String PUBLIC_CONSTANT="Public"; private static final String PRIVATE_CONSTANT="Private"; //Static variables private static int instanceCounter; //Instance variables //Static initializer //Instance initializer //Constructors /** * Constructs a new SourceTemplate with the command line arguments. * * @param args The command line arguments specifying the * work to be done * @throws Exception */ public SourceTemplate(String[] args) { } //Methods /** * Constructs a new SourceTemplate with the command line arguments. * * @throws Exception * @return Text message describing the final result */ public String execute() { return ""; } //Finalizer //Main /* This main is only for testing so I should not go into Java doc */ public static final void main(String[] args) { try { SourceTemplate st = new SourceTemplate(args); System.out.println(st.execute()); } catch(Exception e) { } } |