published

by courtesy of Stephan Janssen
by marc.meurrens@acm.org (http://homepages.ulb.ac.be/~meurrens)

The URL of the original document

by Stephan Janssen (sja@bejug.org) will not be published here.

URL of our page(s) on "Java OO Design & Coding Standards"

(where this document is referred as detailled below):
http://www.ulb.ac.be/esp/ip-Links/Java/joodcs/index.html
[back]

A subset of Stefan Janssen's "FICS Java Coding Standards"

(9 may 1997, rev. 1.33) is available here by courtesy of Stefan; these notes include recommandations used within FICS together with a compilation of usefull rules gathered from various sources; we decided to remove the internal FICS recommandations from the (not publicly available) original document. For more details, contact sja@bejug.org

this mirror (July 8, 1997) reflects the following status...

May 9, 1997 - version 1.33

Created by: Stephan Janssen
Date: 9 May 1997
Version : 1.33
 

1. Introduction

2. Documentation & Structure

2.1. Comments

2.2. Control structures

2.3. Visual layout

3. Naming conventions

3.1. Packages

3.2. Files

3.3. Classes

3.4. Interfaces

3.5. Exceptions

3.6. Constants (finals)

3.7. Methods

3.8. Variables

4. Exception Handling

5. Debug Information

5.1. Debug Switch

6. Version Control

6.1. Using MKS (command line interface)

7. General recommendations

8. Related documents

•   Introduction

  This document contains guidelines for Java coding. These guidelines are not to restrict your programming innovation, but rather to impose a consistent format for our Java programs.

The biggest gains we get by conforming to any coding styles are :

• Easier to maintain code, especially if someone else will do the maintenance.
• Preventing and catching compilation bugs while coding.

 This document is a compilation of existing C++ / Java standard documents that can be found on the net, please refer to the "Related documents" for more information.

•  Documentation & Structure

• Comments

Comments can be divided into two general categories, strategic and tactical.

Strategic comments are used to give the reader a general overview of what is going on. These comments appear at the top of the files and before the function code. Strategic comments tend to be written in a prose style.

Tactical comments are designed to explain tricky areas of code, what parameters do, and hints about the control flow of the program. These comments are imbedded in the code and tend to be shorter and in bullet format.

The javadoc will be used to develop documentation files.

NOTE : Use arguments -version and -author with the javadoc utility to include these tags in your information header.

If you use proper naming, block structure, indentation, and straight forward programming, your code will be mostly self documenting. This is what you should strive for.

• Keep comments simple.
• Do not attempt to explain the obvious.
• Do not use banner-like comments.
• Avoid decoration !

Use the Java (C++) "/*"......"*/" or "/**" …… "*/" construct for all comments. This will allow you to block out sections of code with the old comments and allows you to generate html specific code documents, but this is not necessary in all cases. Please note that this is not applicable for tactical comments !

•  Packages

Create a new java package for each self-contained project or group of related functionality. Create and use directories in accord with java package conventions. (see Naming Conventions for more detailed information on packages)

Consider writing an index.html file in each directory briefly outlining the purpose and structure of the package.

•  Program Files

Place each class in a separate file. This applies even to non-public classes (which are allowed by the Java compiler to be placed in the same file as the main class using them) except in the case of one-shot usages where the non-public class cannot conceivably be used outside of its context.

 Begin each file with a comment including:

• The Source control keywords (e.g., $Author$, $Date$, etc.)
• The file name and/or related identifying information including, if applicable, copyright information.
• A history table listing dates, authors, and summaries of changes.
• If the file contains more than one class, list the classes, along with a very brief description of each.
• If the file introduces a principal entry point for a package, briefly describe the rationale for constructing the package.

Immediately follow each file header with:

• The package name
• The import list.

Example:
 
/**
* $Date$
* $Author$
* $Header$
* $Name$
* $ProjectName$
* File: _________________
* © 1997, FICS Group NV/SA
* Operating Environment: ________________ (optional)
* Compiler: _____________________ (optional)
* Description: _________________________
* Algorithm: (Give a step-by-step alogorithm)
*
* To Do : blablablabla all is done :-)
*
* History :
*
* Date                     Author                          Comments
* -------------------------------------------------------------------------------------------------------------
* 30 May 1997       Stephan Janssen         First release
*
*/

 Each class source file shall terminate with an end of file comment of the form:
 
//end of file test.java

•  Classes & Methods

Each class, method declaration must have a description in comments preceding it. The declaration will contain a comment pertaining to usage, and the definition should contain comments relating to the implementation.

Use javadoc conventions to describe nature, purpose, preconditions, effects, algorithmic notes, usage instructions, reminders,etc.

Use HTML format, with added tags:

• @param paramName description.
• @return description of return value
• @exception exceptionName description
• @see string
• @see URL
• @see classname#methodname

Be as precise as reasonably possible in documenting effects. Here are some conventions and practices for semi-formal specifications.

 @return condition: (condition)

describes postconditions and effects true upon return of a method.

 @exception exceptionName IF (condition)

indicates the conditions under which each exception can be thrown. Include conditions under which uncommon unchecked (undeclared) exceptions can be thrown.  

@param paramname WHERE (condition)

indicates restrictions on argument values. Alternatively, if so implemented, list restrictions alongside the resulting exceptions, for example IllegalArgumentException. In particular, indicate whether reference arguments are allowed to be null.

Before you start coding your class, put general information above the class declaration (such as author, version and other class relations).
See below for example :

/**
* This class handles counters
* @author Stephan Janssen
* @version 1.2 30 May 97
* @see java.lang.date
*/
public class counter {

/**
* This method takes a counter and converts it to the lapsed time
* @return time - time corresponding to program counter
* @param count - the current program count value
*/
public int countTime(int count) {

int time = count * 2;
return time;

}

}
// end of counter.java
 

• Class variables, Local declarations, statements and expressions

 
Use /* ... */ comments to describe algorithmic details, notes, and related documentation that spans more than a few code statements.

Example:
 
/*
* Strategy:
* 1. Find the node
* 2. Clone it
* 3. Ask inserter to add clone
* 4. If successful, delete node
*/

Use running // comments to clarify non-obvious code. But don't bother adding such comments to obvious code; instead try to make code obvious!

Example:

int index = -1; // -1 serves as flag meaning the index isn't valid

Or, often better:

static final int INVALID = -1;
int index = INVALID;

• Control structures
• Visual layout

To make java sources more readable we'll give you some recommendations on java source layout.
This layout will be automatically inforced by a formatting program that will be triggered whenever you call the makefile script.

• Spacing Around Operators

Spacing around operators and delimiters should be consistent. In general, insert one space before or after each operator to improve readability. Use spaces inside of the parentheses around the argument list. Do not use a space within empty argument lists () or non-dimensioned arrays [].

Do not use spaces around the member access operators (. = space)
 
if.(.value.==.0.).{     // right
if.(value==0){          // not recommended

void doIt(.int.v.); // right
void doIt(int.v); // not recommended

 

• Indentation and Braces

The contents of all code blocks should be indented to improve readability. A single tab or four spaces are recommended as the standard indentation. Braces should be placed to show the level of indentation of the code block, with the open brace at the end of the statement which starts the block, and the close brace indented to match the statement.

 void getValue() {

if ( value == 0 ) {
            doSomething();
} else if ( value == 2 ) { // note position of cascaded if statement
            doSomething2();
} else {
            doSomething3();
}

while ( value < 300 ) {

doSomething();

}
 
do {

doSomething();

} while ( value < 300 ) // note: ending brace and control on same line

switch ( value ) {

case 1:    doSomething();
                break;

case 2:
case 3:    doSomething2();
                break;

default:   break; // final break required

}

• 3. Naming conventions
• 3.1. Packages

The location of the packages in the Symantec project files needs to be a relative directory ! We must avoid hard coded settings in the projects files and this to help cross environment / multi-user developing.

• main-package


uppercase : FICS

• sub-packages


lowercase

See the package-based conventions described below :

This section is partially removed in this mirror

• Files

The java compiler enforces the convention that file names have the same base name as the public class they define.


• Classes

FirstWordUpperCaseButInternalWordsCapitalized

When necessary to distinguish from similarly named interfaces:

ClassNameEndsWithImpl (this is used when implementing a Interface !)

or ClassNameEndsWithObject


• Interfaces

When necessary to distinguish from similarly named classes:

FirstWordUpperCaseButInternalWordsCapitalized
 
The implementation of this interface ends with Impl !
 

• Exceptions

classNameEndsWithException


• Constants (finals)

UPPER_CASE_WITH_UNDERSCORES


• Methods

firstWordLowerCaseButInternalWordsCapitalized()


• Variables

firstWordLowerCaseButInternalWordsCapitalized

• Exception Handling

Exceptions are for changing the flow of control when some important or unexpected event, usually an error, has occured. The divert processing to a part of the program that can try to cope with the error, or at least die gracefully. The error can be any condition at all, ranging from "unable to open a file" to "array subscript out of range" to "division by zero".

Java allows you to not bother declaring or catching some common easily-handlable exceptions, for example java.util.NoSuchElementException. We'll NOT CATCH the unchecked exceptions !
  

• Debug Information
• Debug Switch

Code used only during development for debugging or performance monitoring should be conditionally
compiled using specific compile-time switches. The symbols to use are #DEBUG and #END respectively.
 
Debug statements announcing entry into a function or member function should provide the entire function name including the class. For example:

// #DEBUG
Debug.debug("ODM", "ODM::Events: Keyboard error: press F1 to continue J ");
// #ENDDEBUG

 As Java does not support preprocessing we'll simulate this functionality by using a sed script that will

comment or uncomment the lines between #DEBUG / #END when executed !

• Version Control


 

• Using MKS (command line interface)

This section is removed within this mirror

• General recommendations

This list gives you general recommendations on Java programming.

• Minimize * forms of import. Be precise about what you are importing. Check that all declared imports are actually used.

Rationale: Otherwise readers of your code will have a hard time understanding its context and dependencies. Some people even prefer not using import at all (thus requiring that every class reference be fully dot-qualified), which avoids all possible ambiguity at the expense of requiring more source code changes if package names change.

• When sensible, consider writing a main for the principal class in each program file. The main should provide a simple unit test or demo.

 Rationale: Forms a basis for testing. Also provides usage examples.

• For self-standing application programs, the class with main should be separate from those containing normal classes.

 Rationale: Hard-wiring an application program in one of its component class files hinders reuse.

• Consider writing template files for the most common kinds of class files you create: Applets, library classes, application classes.

 Rationale: Simplifies conformance to coding standards.

• If you can conceive of someone else implementing a class's functionality differently, define an interface, not an abstract class. Generally, use abstract classes only when they are ``partially abstract''; i.e., they implement some functionality that must be shared across all subclasses.

Rationale: Interfaces are more flexible than abstract classes. They support multiple inheritance and can be used as `mixins' in otherwise unrelated classes.

• Consider whether any class should implement Cloneable and/or Serializable.

 Rationale: These are ``magic'' interfaces in Java, that automatically add possibly-needed functionality only if so requested.

• Declare a class as final only if it is a subclass or implementation of a class or interface declaring all of its non-implementation-specific methods. (And similarly for final methods).

Rationale: Making a class final means that no one ever has a chance to reimplement functionality. Defining it instead to be a subclass of a base that is not final means that someone at least gets a chance to subclass the base with an alternate implementation. Which will essentially always happen in the long run.

• Never declare instance variables as public.

Rationale: The standard OO reasons. Making variables public gives up control over internal class structure. Also, methods cannot assume that variables have valid values.

• Minimize reliance on implicit initializers for instance variables (such as the fact that reference variables are initialized to null).

Rationale: Minimizes initialization errors.

• Minimize statics (except for static final constants).

Rationale: Static variables act like globals in non-OO languages. They make methods more context-dependent, hide possible side-effects, sometimes present synchronized access problems. and are the source of fragile, non-extensible constructions. Also, neither static variables nor methods are overridable in any useful sense in subclasses.

• Generally prefer long to int, and double to float. But use int for compatibility with standard Java constructs and classes (for the major example, array indexing, and all of the things this implies, for example about maximum sizes of arrays, etc).

Rationale: Arithmetic overflow and underflow can be 4 billion times less likely with longs than ints; similarly, fewer precision problems occur with doubles than floats. On the other hand, because of limitations in Java atomicity guarantees, use of longs and doubles must be synchronized in cases where use of ints and floats sometimes would not be.

• Use final and/or comment conventions to indicate whether instance variables that never have their values changed after construction are intended to be constant (immutable) for the lifetime of the object (versus those that just so happen not to get assigned in a class, but could in a subclass).

Rationale: Access to immutable instance variables generally does not require any synchronization control, but others generally do.

• Generally prefer protected to private.

Rationale: Unless you have good reason for sealing-in a particular strategy for using a variable or method, you might as well plan for change via subclassing. On the other hand, this almost always entails more work. Basing other code in a base class around protected variables and methods is harder, since you you have to either loosen or check assumptions about their properties. (Note that in Java, protected methods are also accessible from unrelated classes in the same package. There is hardly every any reason to exploit this though.)

• Avoid unnecessary instance variable access and update methods. Write get/set-style methods only when they are intrinsic aspects of functionality.

Rationale: Most instance variables in most classes must maintain values that are dependent on those of other instance variables. Allowing them to be read or written in isolation makes it harder to ensure that consistent sets of values are always used.

• Minimize direct internal access to instance variables inside methods. Use protected access and update methods instead (or sometimes public ones if they exist anyway).

Rationale: While inconvenient and sometimes overkill, this allows you to vary synchronization and notification policies associated with variable access and change in the class and/or its subclasses, which is otherwise a serious impediment to extensiblity in concurrent OO programming. (Note: The underscore convention for instance variables serves as an annoying reminder of such issues.)

• Avoid giving a variable the same name as one in a superclass.

 Rationale: This is usually an error. If not, explain the intent.

• Avoid giving a variable the same name as a method.

 Rationale: The compiler will not see this as an error but can cause misinterpretation.

  Rationale: The second form is just for incorrigible C prgrammers.

• Ensure that non-private statics have sensible values even if no instances are ever created. (Similarly ensure that static methods can be executed sensibly.) Use static intitializers (static { ... } ) if necessary.

  Rationale: You cannot assume that non-private statics will be accessed only after instances are constructed.

• Write methods that only do ``one thing''. In particular, separate out methods that change object state from those that just rely upon it. For a classic example in a Stack, prefer having two methods Object top() and void removeTop() versus the single method Object pop() that does both.

  Rationale: This simplifies (sometimes, makes even possible) concurrency control and subclass-based extensions. 

• Define return types as void unless they return results that are not (easily) accessible otherwise. (i.e., hardly ever write ``return this'').

Rationale: While convenient, the resulting method cascades (a.meth1().meth2().meth3()) can be the sources of synchronization problems and other failed expectations about the states of target objects.

• Avoid overloading methods on argument type. (Overriding on arity is OK, as in having a one-argument version versus a two-argument version). If you need to specialize behavior according to the class of an argument, consider instead choosing a general type for the nominal argument type (often Object) and using conditionals checking instanceof. Alternatives include techniques such as double-dispatching, or often best, reformulating methods (and/or those of their arguments) to remove dependence on exact argument type.

Rationale: Java method resolution is static; based on the listed types, not the actual types of argument. This is compounded in the case of non-Object types with coercion charts. In both cases, most programmers have not committed the matching rules to memory. The results can be counterintuitive; thus the source of subtle errors. For example, try to predict the output of this. Then compile and run. 

• We need to contemplate when public methods are synchronized !

Rationale: In the absence of planning out a set of concurrency control policies, in concurrent contexts, every Java program is concurrent to at least some minimal extent). With full synchronization of all methods, the methods may lock up, but the object can never enter in randomly inconsistent states (and thus engage in stupidly or even dangerously wrong behaviors) due to concurrency conflicts.

• Prefer synchronized methods to synchronized blocks.

Rationale: Better encsapsulation; less prone to subclassing snags; can be more efficient.

• If you override Object.equals, also override Object.hashCode, and vice-versa.

Rationale: Essentially all containers and other utilities that group or compare objects in ways depending on equality rely on hashcodes to indicate possible equality. For further guidance see Taligent's Java Cookbook

• Override readObject and WriteObject if a Serializable class relies on any state that could differ across processes, including, in particular, hashCodes. 

Rationale: Otherwise, objects of the class will not transport properly.

• If you think that clone() may be called in a class you write, then explicitly define it (and declare the class to implement Cloneable).

Rationale: The default shallow-copy version of clone might not do what you want.

• Always document the fact that a method invokes wait

Rationale: Clients may need to take special actions to avoid nested monitor calls.  

• Whenever reasonable, define a default (no-argument) constructor so objects can be created via Class.newInstance().

Rationale: This allows classes of types unknown at compile time to be dynamically loaded and instantiated (as is done for example when loading unknown Applets from html pages). 

• Prefer abstract methods in base classes to those with default no-op implementations. (Also, if there is a common default implementation, consider instead writing it as a protected method so that subclass authors can just write a one-line implementation to call the default.)

Rationale: The Java compiler will force subclass authors to implement abstract methods, avoiding problems occurring when they forget to do so but should have. 

• Use method equals instead of operator == when comparing objects. In particular, do not use == to compare Strings.

Rationale: If someone defined an equals method to compare objects, then they want you to use it. Otherwise, the default implementation of Object.equals is just to use ==. 

• Always embed wait statements in while loops that re-wait if the condition being waited for does not hold.

Rationale: When a wait wakes up, it does not know if the condition it is waiting for is true or not.

• Use notifyAll instead of notify or resume.

Rationale: Classes that use only notify can normally only support at most one kind of wait condition across all methods in the class and all possible subclasses. And unguarded suspends/resumes are even more fragile. 

• Declare a local variable only at that point in the code where you know what its initial value should be.

  Rationale: Minimizes bad assumptions about values of variables.

•   Declare and initialize a new local variable rather than reusing (reassigning) an existing one whose value happens to no longer be used at that program point.

Rationale: Minimizes bad assumptions about values of variables.

• Assign null to any reference variable that is no longer being used. (This includes, especially, elements of arrays.)

Rationale: Enables garbage collection.

• Avoid assignments (``='') inside if and while conditions.

Rationale: There are almost always typos. The java compiler catches cases where ``='' should have been ``=='' except when the variable is a boolean.

• Document cases where the return value of a called method is ignored.

Rationale: These are typically errors. If it is by intention, make the intent clear. A simple way to do this is: int unused = obj.methodReturningInt(args); 

• Embed casts in conditionals. For example:

C cx = null;
if (x instanceof C) cx = (C)x;
else evasiveAction();

Rationale: This forces you to consider what to do if the object is not an instance of the intended class rather than just generating a ClassCastException.

Rationale: See Jonathan Hardwick's Java Optimization pages.

• Do not require 100% conformance to rules of thumb such as the ones listed here!

Rationale: Java allows you program in ways that do not conform to these rules for good reason. Sometimes they provide the only reasonable ways to implement things. And some of these rules make programs less efficient than they might otherwise be, so are meant to be concientiously broken when performance is an issue.

• Related documents

For some other standards and style guides, see :

• The Coding Standards Repository for various languages.(mirrored here)

• Draft Java Coding Standard by Doug Lea.(mirrored here)

• Coding Standards for C, C++, and Java by Vision 2000 CCS Package and Application Team.(mirrored here)

• Kent Sandvik's Java Coding Style Guidelines(mirrored here)

• Taligent's Java Cookbook for porting C++ to Java.(mirrored here)

• Naval Postgraduate School Java Style Guide. (mirrored here)

Brussels July 8, 1997 mirror of internal work dated "May 9, 1997 - version 1.33" by Stephan Janssen (sja@bejug.org) published by marc.meurrens@acm.org (http://homepages.ulb.ac.be/~meurrens) original URL: $source-URL$ current URL: http://www.ulb.ac.be/esp/ip-Links/Java/joodcs/Stephan.html internet programming Links: http://www.ulb.ac.be/esp/ip-Links (ip-Links) Université Libre de Bruxelles: http://www.ulb.ac.be (ULB) La Cambre - Architecture: http://www.lacambre-archi.be Belgian JAVA User Group: http://www.bejug.org (BeJUG)

Use this form to send your feedback and/or submit a link To sja@bejug.org ; fon@bejug.org ; sja@ficsgrp.com ; meurrens@ulb.ac.be Subject Your URL Your comment Your e_mail

Conventions used in these pages: html file, text file or java or CPP source located on our site download area (on our site) or file to be downloaded (use the right button of your mouse) document on a belgian academic or scientific site document (on another site) or link to be fixed or link we didn't visit/evaluate; documents indicated with their full URL will be displayed in their own "top" window. ftp download or file to be downloaded (use the right button of your mouse) indicates a "mailto" link. Click on the separator to reach a higher level in the page or site hierarchy.

back home e_mail ULB ESP ip-Links La Cambre BeJUG