Java Coding Standard

GENERIC

JAVA CODING STANDARD

@(#)GenericJavaCodeStd.htm 1.3 - 07/27/05

The Generic UWF Maintenance Process (GUMP++) 1994-2001 The University of West Florida. All rights reserved.

Permission is granted to reproduce and adapt this document provided credit is given to the University of West Florida. This documentation is provided "as is" and no warranty of fitness for any particular purpose is made or implied.

ABSTRACT

This document is the Java Coding Standard document for the generic maintenance process architecture for the University of West Florida. It describes which Java Code Conventions should be used for the project. Coders should follow these conventions to the maximum extent possible in order to ensure a uniform appearance and improve maintainability.

ABSTRACT
1.0 INTRODUCTION
2.0 RECOMMENDATION
2.1 SUN'S CODE CONVENTIONS
2.2 ORDER OF METHOD IN A CLASS
2.3 CLASS TESTS
3.0 UNIT TEST
3.1 UNIT TEST STANDARD
3.2 EXCEPTION
3.3 EXAMPLE
4.0 ASSERTIONS AND SELF CHECKS

1.0 INTRODUCTION

This Java Coding Standard describes the conventions that should be followed in all new Java code.

2.0 RECOMMENDATIONS

2.1 Sun's Code Conventions

Our code should generally follow Sun's Java Code Conventios, available at: Java Sun. Minor difference, such as in the number of spaces or style of indentation are acceptable.

2.2 Order of Methods in a Class

Sun's standard leaves open the ordering of methods in a class. We suggest that static methods should be grouped first, and that the instance methods should be in alphabetical order to make them easier to find.

2.3 Class Tests

Most classes should have a main() function that runs a set of class tests.

3.0 UNIT TEST

3.1 Unit Test Standard

The following items are a standard to go by for Unit Tests in java classes.

Have a main() in each class that will execute unit tests for that certain class.
Main() will call a local function in that class called classTest().
classTest() will return a Boolean value.
This Boolean will be a TRUE if the class test passes and a FALSE if the class test fails.
Unit tests in the class will be numbered (e.g., Test 01, Test 02).
A test might have more than one case, so you would use, for example Test 1A and Test 1B.
Have comments above each test that state the test number and explain exactly what that unit test is doing.
When reporting the results to System.out, you would state the class name, the test number and the result (e.g., Test 2 R3ualibtTSContinuingFile PASSED).

3.2 Exception

Some classes, such as GUI classes, can't be unit tested automatically because they require user input or user examination of results.

3.3 Example

See the main() and classTest() methods of Recon3 file r3ualibt.R3ualibtFTERecon3BySource.java as a good example of the organization of unit tests.

4.0 Assertions and Self Checks

Programmers are strongly recommended to make extensive use of assertions and other self checks in their Java code. Sun's document Programming With Assertions explains what assertions are and gives recommended practice on when and when not to use them. Please follow these guidelines.

Note specifically that assertions are intended for preconditions, post conditions and class invariants, but not for argument checking of public methods. Argument checks of public methods should instead throw an unchecked exception such as IllegalArgumentException.

When running tests, it is important to make sure that assertions are enabled. Otherwise these self checks will not be useful. To enable assertions the "java ..." command must be "java -ea ...". Use this form when running the command by hand or add the "-ea" parameter to your programming environment's run command. (In Eclipse 3.0 for example, choose "Run ..." from the Run menu, and create a configuration that has this parameter.)

To guarantee that assertions are enabled when running the unit test main() of each class, add a self check as in the following example main():

  public static void main( String[] args ) {
    // Error if unit tests are run without assertions enabled
    boolean assertsEnabled = false;
    assert assertsEnabled = true; // intentional side effect
    if (!assertsEnabled)
      throw new RuntimeException("Assertions must be enabled for unit tests");
    //
    // code to run the classTest() method here
    // ...
    System.exit(0);
  }

REVISION HISTORY

January 2002
Lily Rakar

February 2002
Ryan Ingram, Lily Rakar

July 2005 - added material about assertions and unit test example.
Norman Wilde

GENERIC