Home : Course Map : Chapter 5 : Java :
Coding Conventions
JavaTech
Course Map
Chapter 5
File/Package/Import
  Demo 1
  Demo 2
Access/Visibility
final & Constants
Static Import
Jar Files
  Demo 3
Applet Directories
3rd Party Packages
CLASSPATH
javadoc
CodingConventions
Exercises

    Supplements
Scope
Debug Techniques
Java Runtime
Class Class
JVM Instructions 2
JVM Processing
pack200

     About JavaTech
     Codes List
     Exercises
     Feedback
     References
     Resources
     Tips
     Topic Index
     Course Guide
     What's New

As with any programming language, you should strive to make your Java programs as readable and understandable as possible, both for yourself as well as for others who might use your code. This means clear, concise, and plentiful comments and descriptive, informative names for classes, methods and variables. Furthermore, a consistency in the style of the code helps both in reading and debugging your programs.

There are a number of Java coding standards that have been proposed. For our demonstration programs in the following chapters, we follow the guidelines set out by noted Java guru Doug Lea. The full standard is too lengthy to include here but we give the essentials that suffice for our short demos.

Our naming conventions go as follows.

  • OurClass - class names use concatenated words with the first letter of each word uppercase
  • ourMethod () - non-private methods use concatenated words with first letter lowercase and the first letter of each subsequent word uppercase
  • a_priv_method () - private methods use lower case words separated by "_"
  • fOurInstanceVar - member variables start with "f" (for field) and consist of concatenated words with the first letter of each word uppercase
  • our_local_var - local variables are in lower case with the words separated by "_".
  • fOurStaticVar__ - static variables begin with "f" like member variables but end with two "_" characters.
  • javatech.pack - package names use lower case
  • A_CONSTANT_VAL - constants are upper case words separated by "_"

Our interfaces are distinguished from classes by appending "Ifc" or "able". We use javadoc comments before each class and method (unless they are short and obvious). We terminate them with "**/" for symmetry with the "/**" that must start a javadoc comment.

The sample code shown below illustrates the code styling we use for the remainder of this book. Each distinct code section, such as a method or an if-else statement, is indented to the right from the section in which it is nested. All primitive variables are initialized explicitly. (Default values would be assigned automatically but by initializing them you make clear that the values given are what you intended for those variables.)

For the class definition and for long methods we put the name in a comment after the final brace. (We use "// ctor" for long constructors.)

// Non javadoc comments, authorship, and
// class development history.

package javatech.xxx.yyy.zzz;

import java.io.*;

/** javadoc comments about the class. **/
public class SomeClassName
{
  int fInstanceVal = 1;
  double fVal = 0;
  Integer fInstanceRef;

public SomeClassName {
   ... constructor code ...
} // ctor - for longer constructors

/** Describe the method. **/
  public void methodName (...) {
    int x = 5;
    some_method (x);
    if (test) {
      do_something ();
    }
    else {
      ...
    }
    ...
    try {
      xxx ();
    }
    catch (Exception e) {
      handle_it ();
    }
  } // methodName - for longer methods

  /** Longer comment.
   * - this asterisk is ignored by javadoc
   **/
  public void someMethodWithLotsOfParameters (
    int param1,
    int param2,
    etc.
  ) throws SomeException {
    ...
  } // someMethodWithLotsOfParameters

  /** Private method names with underscores. **/
  private void some_method (int i) {
    ...
  } // some_method

  /** Getter method. **/
  double getVal () {
    return fVal;
  }

  /** Setter method. **/
  void setVel (double val) {
    fVal = val;
  }

} // class SomeClassName

 

The getVal() and setVal() are examples of the common getter and setter methods use to get and set the value of a particular variable whose name is included in the method name. In this way we follow the important JavaBeans standard although the use of JavaBeans is not discussed here.

We also note that the consistent use of the fMemberVariable notation for member variables and local_variable_name notation for local variables inside a method makes it impossible to accidentally shadow a member variable with a local variable

Note: Shadowing occurs when a subclass has a data field or local variable with the same name as that of a data field in a super class. This is almost never useful and should be avoided.

References and Web Resources

Latest Update: Oct. 22, 2004

            Tech
DecimalFormat
  Demo 1
  Demo 2

System.out.printf
  Demo 3
CJ Format Class
  Demo 4   Demo 5
Other Format Tools

Immutable Complex
Exercises

           Physics
Interpolation
Integration
  Demo 1
Simpson Rule
  Demo 2
Exercises

  Part I Part II Part III
Java Core 1  2  3  4  5  6  7  8  9  10  11  12 13 14 15 16 17
18 19 20
21
22 23 24
Supplements

1  2  3  4  5  6  7  8  9  10  11  12

Tech 1  2  3  4  5  6  7  8  9  10  11  12
Physics 1  2  3  4  5  6  7  8  9  10  11  12

Java is a trademark of Sun Microsystems, Inc.