The Otego AG Java Coding Standard

$Revision: 1.9 $, $Date: 2002/03/18 07:18:47 $, Last changing $Author: giacomo $

Table of Contents

• Introduction
• Structure
• Documentation
• Naming Conventions
• Test Case
• Recommendations
• Tools
• References

Introduction

Code standards aren't just about obsession, they are about productivity, professionalism, and presentation. This code standard for Java is adhered to by the Otego AG so that our resulting product is more readable, maintainable, robust, testable, and professional.

Many people helped with the evolution of this code standard. These practices were not created in a vacuum. They are tried and true rules that have been used in producing both research and commercial systems by teams of dozens of programmers. While not all the rules are applicable to every developer or all systems, a general adherence to the rules and a belief in software engineering practices often results in happier and healthier developers and systems.

Structure

In the context of this document, "structure" means "organization, look, and feel" of a body of code. It includes elements of system and subsystem organization (packages), documentation (Javadoc tags, inline comments, and index files), specification (more Javadoc tags, running comments, index files), and development (code organization). Adhering to these standards means that every piece of code has the same structure so that a reader can instantly know where to find a piece of information (attribute, import, method, etc.) without have to search through an entire source file.

Packages

Create a new Java package for each self-contained project or set of related functionality, in accordance with the following package naming guidelines (including a directory structure which corresponds to the package naming, as per Java conventions):

• Globally unique package naming is obtained by building a package hierarchy using the reversed domain name of your organization. Thus, all of our projects fall under the com.otego package hierarchy.
• If a package is part of a larger project, make it a subpackage of a reasonably-named top-level package. For example, code written for the OTGBRIDGE project might be placed in subpackages of com.otego.otgbridge.
• Package names should be all lower-case.
• Package names should conform to existing Java examples when appropriate. E.g., for I/O classes, make an io package similar to java.io. Other examples include java.lang, java.net, java.util, and java.math.

Provide a package.html file in each package directory briefly outlining the purpose and structure of the package. This file is used by Javadoc (in Java 1.2 and later) as package commentary, and also serves as local documentation for your code tree. For more information on the format of this file as used by Javadoc, see the package-level comments documentation on Sun's web site. If you plan to allow local browsing of your source tree, you should alias this file to index.html so that it serves as the default index file for the directory.

Program Files

Place each and every 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. One example of such usage is the creation of Event classes in AWT 1.1 programming.

Begin each file with a comment block containing at least the following information (example below):

1. Any copyright information relevant to the project.

Immediately follow the file header with:

• The package statement.
• The import list, ordered according to the following rules:
  1. Core imports of the form "import java.<packagename>" are listed last; imports of standard Java extensions of the form "import javax.<packagename>" are listed second last; and all remaining imports come first.
  2. Import lists (other, extension and core) are sorted in alphabetic order independently.
  3. Avoid import lines which use the '*' construct (like "import java.io.*"). Using this construct makes it difficult to determine exactly which classes are referenced by your class without detailed inspection of the code.

Example file header:

/*****************************************************************************
 * Copyright (C) 2002 Otego AG, Switzerland. All rights reserved.            *
 * ------------------------------------------------------------------------- *
 * This software is published under the terms of the otego Software License  *
 * version 1.0, a copy of which has been included with this distribution in  *
 * the LICENSE file.                                                         *
 *****************************************************************************/

package com.otego.project.sample;

import com.otego.project.otherpackage.FooObject;
import com.otego.project.otherpackage.MyObject;

import com.otego.otherproject.somepackage.MyObject;

import javax.management.timer.TimerMBean;
import javax.xml.parsers.SAXParser;

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.io.IOException;
import java.util.Vector;

Classes and Interfaces

Write all /** ... **/ comments using Javadoc conventions. Even though it is not required by Javadoc, end each /** comment with **/ to make it easier to read and check.

Preface each class with a /** ... **/ comment describing the purpose of the class, guaranteed invariants, usage instructions, and/or usage examples. The beginning of the comment should be a description of the class in exactly one sentence. Also include any reminders or disclaimers about required or desired improvements. Use HTML format when appropriate, but do not forget that all inline text is parsed as HTML format, so accidental use of HTML elements can result in strange looking documentation. See the below chart for appropriate tags and usages.

Each class comment block must include exactly one @version tag and at least one @author tag. The @author tags often list everyone who has written more than a few lines of the class. Each @author tag should list exactly one author including its email address. The @version tag's version is a project specific string (e.g. "${version}") which will be replaced by Jakarta Ant (our preferred project building tool) followed by a CVS/RCS $Id$ tag. Additionally, each class can optionally contain a // comment after its closing brace stating that the class declaration has ended.

Example class comment block:

<file header, package name and imports, as above>

/**
 * A class representing the archetypical class from which one can
 * learn code standards through example.
 *
 * Usage example:
 * <CODE>
 * 	ArchetypeClass ac = new ArchetypeClass();
 *	ac.init();
 * </CODE>
 *
 * @see     ArchetypeAbstractClass
 * @see     ArchetypeInterface
 * @see     java.lang.Object
 * @version ${version} $Id: java_standard.html,v 1.9 2002/03/18 07:18:47 giacomo Exp $
 * @author <a href="mailto:giacomo.pati@otego.com">Giacomo Pati</a>
 * @author <a href="mailto:martin.biel@otego.com">Martin Biel</a>
 **/

public class ArchetypeClass extends AnotherClass
    implements FooInterface, BarInterface
{
  ...
}

// end of class ArchetypeClass

Class (Static)/Instance Fields

Use Javadoc conventions to describe the nature, purpose, constraints, and usage of static fields and instance fields. See the chart below for appropriate tags and usages. All static fields should appear together, before the set of method declarations; all instance fields should likewise appear together, after the set of static fields (but always before the method declarations). The sets of static and instance fields should be clearly offset by comments (the format of these comments is left to the individual programmer, though they should be clear).

For example:

public class Example
{
    // Static Fields

    /**
     * This is a static field.
     **/

    priivate static String m_staticString = "Static String";


    // Instance Fields

    /**
     * This is an instance field.
     **/

    protected String m_instanceString = "Instance String";


    // Method Declarations

    ...
}

Methods

Method parameters should be cleanly organized, either on a single line or one per line. All static methods should appear together; the same goes for instance methods. These blocks of methods should be clearly delineated with comments (as for blocks of variables, above). Some examples of acceptable method declarations:

  public static int aMethod( final String aString, final int anInt, final double aDouble );

  public synchronized Exception anotherMethod( final String aString,
                                               final int anInt,
                                               final double aDouble );

  public final Event yetAnotherMethod(
      final Long aLongObject, 
      final String aString, 
      final Double aDoubleObject );

                                       

Whenever possible use the final modifier for variables, methods and arguments. This enable the most performance optimization and security constraints possible.

Use Javadoc conventions to describe nature, purpose, preconditions, effects, algorithmic notes, usage instructions, reminders, etc. The beginning of a method comment should be a summary of the method. Use HTML format when appropriate. See the chart below for appropriate tags and usages.

In all of the following tags, Expression means (OCL-Expression | code segment | natural language description). An OCL-Expression is an expression in the Object Constraint Language; see Joe for more information. A code segment is a legal expression from any programming language, but is most often written in the language of the code it documenting, in this case Java. A natural language description is a description written in a spoken language (like English).

For all tags, entities enclosed in () or <> must be so enclosed when using the tags. E.g. "(Expression)" means literally "(" + the expression + ")". Entities enclosed in [] in the table indicate optional entities and should not use literal square brackets.

The table lists, in the "Usage" column, the Java entities to which each tag is applicable. Possible values for this column are classes, interfaces, methods, fields (that is, instance fields and static fields of a class or interface), all (which means "classes, interfaces, methods and fields"), and special (special usages explained in the "Purpose/Description" column).

More detailed information on the syntax of the standard Javadoc tags described here (most notably, @see, {@link} and the serialization-related tags) is available from Sun's Javadoc Home Page.

Javadoc Tag Conventions

    @deprecated Replaced by setBounds( int, int, int, int ).

  /**
   * @hides java.util.Vector.elementCount
   **/

  protected long elementCount = 0;
    

  /**
   * @overrides java.util.Vector.clone() We need to provide a deep clone. 
   **/

  public synchronized Object clone();

@see java.lang                          //  java.lang
@see java.lang.String                   //  String 
@see java.lang.String The String class  //  The String class
@see String                             //  String
@see String#equals( Objetc )            //  String.equals( Object )
@see String#equals                      //  String.equals( java.lang.Object )
@see java.lang.Object#wait( long )      //  java.lang.Object.wait( long )
@see Character#MAX_RADIX                //  Character.MAX_RADIX
@see <A HREF="spec.html">Java Spec</a>  //  Java Spec       

      
    @see java.io.File#File( java.io.File, java.lang.String )

Always be as precise as reasonably possible in documenting effects.

Code Layout

A consistent code layout style improves code readability, maintainability, and robustness. We use xemacs for automatic code layout. Our code layout rules are as follows:

• Indention consists of spaces only (in particular, no tab characters are allowed).
• Each indent level is exactly four spaces.
• Method declarations are seperated from the comments of the following method by at least one lines of white space.
• Comments immediately preceed method, field and class declarations (no lines of white space).
• Complex expressions are fully parenthesized, for readability and clarity. Put a space after an opening parenthesis as well as before a closing parenthesis .
• Left-brace ("{") placement occurs at the beginning of the next line of code in all cases (including empty blocks). Code follows on the next line, indented by four spaces. The xemacs code block provided below guarantees this indentation behavior. For example:

        
        for ( int i = 0; i < 100; i++ )
        {
            // this is where the code begins
            a = i * i;
        }
        
        

• Braces are vertically aligned to highlight code blocks.
• Each long and/or complex code block should have its closing brace commented to clearly identify the block being closed by the brace.
• The maximum line length is 78 characters.
• Spill-over indentation for breaking up long lines is allowed (and, in fact, encouraged).
• All class fields are declared at the top of the class.
• Methods should be declared in the following order: constructors, finalizers, initializers, static methods, then blocks of public instance methods with their private helper methods. The exception to this is static initializers, which should appear in between the static and instance fields.
• All binary operations (+, /, *, etc.) and assignments should be buffered by a single space. Unary operations (like -, !, and ++) should not be separated by their operands. For example:

        
        double x = ( y + z );
        double a = ( Math.pow(x) * ( 1.23 + 4.56 ) ) * 2.0;
        a += 3.1415;
        x++;
        boolean b = !( a == 1.0 );
        
        

• Guard expressions in conditionals and loops should be separated from their keywords by exactly one space. Moreover, brackets should always be used for conditional and loop blocks, even those which consist of a single instruction. For example:

        
        for ( int x = 1; x < 100; x++ )
        {
            // do something
          
            if ( x == 2 )
            {
                // a single line of code
            }
          
            while ( (x % 2) == 0 )
            {
                // multiple lines
                // of code
            }
          
            switch ( x )
            {
                case 1:
                {
                    // some code
                }
          
                default:
                {
                    // more code
                }
            }
        }
        
        

• Static and instance fields should be organized (within their blocks) in the following order: public, protected, private.

XEmacs-specific Code Standard Support

The following elisp code expressions can be added to your .xemacs/init.el startup file to institute all of the above standards (except the brackets for every block of code in a conditional or loop) automatically. Note that, in fact, it is actually much safer just to take someone's working .xemacs/init.el file and customize it for yourself. This way, subtle dependencies in the setup are handled.

Here is the elisp code:

;; Indentation Settings

;; preload cc-mode to make settings
(require 'cc-mode)

;; indents are in blocks of two spaces
(setq-default c-basic-offset 4)

;; make sure we don't use tabs in indents
(setq-default indent-tabs-mode nil)

(cond ((or (string-match "4." c-version)
           (string-match "5." c-version))

       ;; Setup for CC-mode version 4 and above.
       
       ;; Set up indention for programming in C, C++, Objective C, and
       ;; Java

       (defun c-lineup-javadoc-comments (langelem)
         ;; Define a new custom indentation function for handling
         ;; Javadoc comments.  Line up all first *'s.  First create a
         ;; new context so the point, mark, and current buffer are not
         ;; munged, even in the case of abnormal exit.
         (save-excursion
           ;; goto the point that is defining our indention depth
           (goto-char (cdr langelem))
           ;; is it the first line of a javadoc comment?
           (if (looking-at "/\\*")
               ;; yes! so return a 1
               1
               0)))

       ;; We define a new CC-mode style for our group's code standards.
       ;; We'll call this style "caltech-java".
       (defconst caltech-java-style
           '((c-basic-offset . 2)
             (c-comment-only-line-offset . (0 . 0))
             (c-offsets-alist . 
              ((access-label          . 0)
               (arglist-close         . c-lineup-arglist)
               (arglist-intro         . c-lineup-arglist-intro-after-paren)
               (c                     . c-lineup-javadoc-comments)
               (case-label            . +)
               (inher-cont            . c-lineup-java-inher)
               (inline-open           . 0)
               (knr-argdecl-intro     . 5)
               (label                 . +)
               (statement-case-open   . +)
               (statement-cont        . 0)
               (substatement-open     . 0)
               (statement-block-intro . +)
               (topmost-intro-cont    . +)))))

       ;; Customizations for all c-mode, c++-mode, objc-mode, and java-mode.

       (defun caltech-java-mode-hook ()
         "Hooking in the Caltech Infospheres code standard for CC-mode
version 4 and turning on cc mode's minor modes."
         ;; Add caltech-java style and set it for the current buffer.
         (c-add-style "caltech-java" caltech-java-style t)
         ;; Add any user-specific customizations here (should be none).
         ;;
         ;; CC Mode has two minor modes; auto-newline and hungry-delete.
         ;; If you don't like the behavior of either of these minor modes,
         ;; comment out the following expression.  More information on
         ;; these minor modes is available in the CC Mode info pages.
         (c-toggle-auto-hungry-state 1)
         ;; Keybindings for all supported languages can be added here.
         ;; We can upt these in c-mode-map because all the other maps
         ;; inherit from it.
         ;; (define-key c-mode-map <key> <func>)
         )

       ;; Add hook to Java mode to start everything up everytime we
       ;; enter a Java buffer.
       (add-hook 'java-mode-hook 'caltech-java-mode-hook))

      ((string-match "3." c-version)

       ;; Customization for CC-mode version 3.
       ))

The following elisp code expressions can also be added to your .xemacs/init.el startup file to check your current xemacs buffer according to the coding convention stated in this document by use of a customized checkstyle tool.

Documentation

What's the point?

Documentation is all about communication. If you have any hope or desire to see your code understood and reused, it needs to be completely and thoroughly documented.

How much is enough?

Your guiding metric for "How much is enough?" should be the following: Communicate exactly enough information in your comments to the reader so that they could implement what you are describing and do so correctly.

Self-documenting code

Some argue that the code itself should be "self-documenting". This is true, in some sense, and we enforce it in some ways through naming conventions and running comments, but it isn't enough. What about the reader who doesn't know the language you are coding in? What about proprietary reusable components? Obviously, something more is necessary.

Real coders don't document

Also, for those of you that think that documenting is for weaklings and that real hackers/masters/Rambo-coders don't need comments; believe us, we could find some code that you wouldn't understand even with days of head-scratching (if you're in the area, drop by and we'll prove it). Rambo-coders need not apply.

Local declarations, statements, and expressions

Use /* ... */ comments only to temporarily comment out blocks of code. Otherwise, only C++-style (//) comments should be used to describe algorithmic details, notes, and related documentation which 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. However, always prefer making the code more obvious to commenting it because it is non-obvious, and don't bother commenting obvious code.

Example:

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

Or, even better:

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

Naming Conventions

You can name your temporary and loop variables anything you like, (we suggest prefixes of temp and loop), but all your other variables, especially static and instance fields of your objects, must have some sort of uniform naming scheme. The follow specification of naming standards follows the conventions of several organizations and individuals. It has been created by committee, however, so it probably won't completely satisfy or dissatisfy any individual.

Test Case

TestCases for Avalon Components usually extend the org.apache.avalon.excalibur.testcase.ExcaliburTestCase class which creates an Avalon environment including a ComponentManager, LogKit configuration, and Component Configuration for your Components.

Recommendations

The following are coding recommendations. It is not necessary to follow them to the letter, but we have found it helpful to always keep them in mind.

Do not use the * form 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. (We, however, aren't that freaky.)

For standalone application programs, the class with the main() method should be separate from those containing normal classes.

Rationale: Hard-wiring an application program in one of its component class files limits the potential for class reuse.

If you can conceive of someone else implementing a class's functionality differently, define an interface rather than 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 carefully whether any class should implement the Cloneable and/or Serializable interfaces.

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 (a similar principle applies to the declaration of final methods).

Rationale: Making a class final means that no one will ever get a chance to reimplement its 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 fields as public.

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

Minimize statics (except for static final constants).

Rationale: Static fields 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 fields nor static methods are overridable in any useful sense in subclasses.

Use final and/or comment conventions (see the @modifies and @values tags) to indicate whether instance fields, local fields and argument fields that never have their values changed after construction are intended to be constant (immutable) for the lifetime of the object (as opposed to those that just happen not to get assigned in a class, but could in a subclass).

Rationale: Access to immutable instance fields generally does not require any synchronization control, but access to mutable fields generally does.

Generally prefer protected to private.

Rationale: Unless you have good reason for sealing-in a particular strategy for using a field 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 fields and methods is harder, since 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 ever any reason to exploit this, though.)

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

Rationale: Most instance fields in most classes must maintain values that are dependent on those of other instance fields. 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 fields 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 field access and change in the class and/or its subclasses, which is otherwise a serious impediment to extensiblity in concurrent OO programming.

Avoid giving a field the same name as one in a superclass.

Rationale: This is usually an error. If not, there must be a very good reason, which should always be explained (in a @hides tag).

Declare arrays as Type[] arrayName rather than Type arrayName[].

Rationale: The second form exists solely for incorrigible C programmers, and makes code less easily readable.

Ensure that non-private static fields have sensible values, and that non-private static methods can be executed sensibly, even if no instances are ever created. 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. A classic example: in a Stack class, prefer having two methods Object top() and void removeTop() to having 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., refrain from ever writing "return this;").

Rationale: While convenient, the resulting method cascades (a.meth1().meth2().meth3()) can be 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, Serializable or Cloneable) and using conditionals which check instanceof (or, reflectively, isAssignableFrom()). Alternatives include techniques such as double-dispatching or, often best, reformulating methods (and/or their arguments) to remove dependence on exact argument type.

Rationale: Java method resolution is static, based on the listed types rather than the actual argument types. 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.

     

class Classifier
{
    String identify( Object x )
    {
        return "object";
    }
    String identify( Integer x )
    {
        return "integer";
    }
}

class Relay
{
    String relay( Object obj )
    { 
        return (new Classifier()).identify( obj );
    }
}

public class App
{
    public static void main( String [] args )
    {
        Relay relayer = new Relay();
        Integer i = new Integer( 17 );
        System.out.println(relayer.relay( i ));
    }
}
    

Declare @concurrency values for all public methods. Describe the assumed invocation context and/or rationale for existence or lack of synchronization. If you don't know the concurrency semantics of your method, make it synchronized.

Rationale: In the absence of planning out a set of concurrency control policies, declaring methods as synchronized at least guarantees safety (though not necessarily liveness) 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 into randomly inconsistent states (and thus engage in stupidly or even dangerously wrong behavior) due to concurrency conflicts. If you are worried about efficiency problems due to synchronization, learn enough about concurrent OO programming to plan out more efficient and/or less deadlock-prone policies (i.e., read "Concurrent Programming in Java" by Doug Lea).

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 and transient fields.

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 (and, in fact, does not in most cases).

Always document the fact that a method invokes wait().

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

Initialize all (reasonable) fields in all constructors, or do not initialize any fields in any constructors (rely on explicit or implicit initialization in field declarations) and always explicitly call the superclass constructor.

If you don't initialize it, you don't know what value it really holds. Consistency is the key in this rule so that a reviewer/user/tool doesn't have to search around for every initialization.

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). In Java 1.1 and later, reflection alleviates the need for no-argument constructors somewhat, but many classes which dynamically instantiate other classes at runtime still depend on their presence.

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 which occur when they forget to do so but should have.

Always 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 ==.

Never use suspend()/resume() pairs to implement synchronization with threads.

Rationale: The suspend() and resume() are inherently fragile, and have even been deprecated by JavaSoft as of JDK 1.2.

Always embed wait() calls in while loops which re-wait if the condition being waited for does not hold.

Rationale: When a wait() wakes up, there is no guarantee that the condition it is waiting for has become true.

Use notifyAll() instead of notify().

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.

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. Of course, you should know about the initial value of most local variables at the beginning of the method. Only one-off (temporary, loop, etc.) variables should be declared within the body of a method.

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 which is no longer being used. This includes, especially, elements of arrays.

Rationale: Enables the Java garbage collector to do its job.

Avoid assignments ("=") inside if and while conditions.

Rationale: These 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 usually errors. If it is intentional, make the intent clear. A simple way to do this is: int unused = obj.methodReturningInt (args);

Ensure that there is ultimately a catch for all unchecked exceptions that can be dealt with.

Rationale: Java allows you to not bother declaring or catching some common easily-handlable exceptions, for example java.util.NoSuchElementException. Declare and catch them anyway. It'll make your code more robust.

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.

Document fragile constructions used solely for the sake of optimization.

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 they are meant to be conscientiously broken when performance is an issue.

Tools

Ant

All our projects are build by Ant

You'll find a distribution in the Distribution Section of the Otego Intranet site.

Emacs

The canonical summary: Emacs is the extensible, customizable, self-documenting real-time display editor.

(Rewritten from the XEmacs home page) Emacs is a powerful, extensible text editor with full GUI and terminal support.

Two primary supported free implementations of Emacs exist:

FSF Emacs, the Free Software Foundation's mainline Emacs implementation, and
• XEmacs, a highly graphical version initially based on an early version of GNU Emacs 19 from the Free Software Foundation and since kept up to date with recent versions of that product. XEmacs stems from a collaboration of Lucid, Inc. with Sun Microsystems, Inc. and the University of Illinois, with additional support having been provided by Amdahl Corporation and Altrasoft.

Extending Emacs. (X)Emacs is extended through the use of Emacs LISP packages. The primary packages we use for the development of Java are as follows (this list is by no means complete and reflects our personal biases):

• CC-mode. This is a GNU Emacs mode for editing files containing C, C++, Objective-C, Java, and CORBA IDL code. CC-mode support template insertion, auto-indenting, key shortcuts for often used expressions and blocks and much, much more. Documentation on cc-mode can be found in the info pages of your emacs process (type control-h then 'i').
• JDE: The Java Development Environment for Emacs. (from the JDE home page): The JDE is an Emacs Lisp package that provides a highly configurable Emacs wrapper for command-line Java development tools, such as those provided in JavaSoft's JDK. The JDE provides menu access to a Java compiler, debugger, and API documenter. The Emacs/JDE combination adds features typically missing from command-line tools, including:
  • syntax coloring
  • auto indentation
  • compile error to source links
  • source-level debugging
  • source code browsing

  The JDE supports both Emacs (Unix and Windows versions) and XEmacs. It is freely available under the GNU public license.
  (Ed. note --- note that much of the functionality of JDE is simply JDE using other packages like cc-mode, font-lock-mode, etc. It does pull all of these packages together very well.)

• Tags. (from XEmacs info documentation node (xemacs)Tags:) A "tags table" is a description of how a multi-file program is broken up into files. It lists the names of the component files and the names and positions of the functions (or other named subunits) in each file. Grouping the related files makes it possible to search or replace through all the files with one command. Recording the function names and positions makes possible the `M-.' command which finds the definition of a function by looking up which of the files it is in.

  Briefly, using tags with Java means that your emacs knows the location and completion of all interesting features (classes, interfaces, fields, methods, etc.) of your project so that you can (a) jump right to the feature definitions, (b) use completion (see the next bullet), (c) do regular expression searches and/or replaces on tags (e.g. global replace of a variable), and more. See the documentation on tags in Emacs info for more information on the use of tags.

• Completion. When using tags or OOBR, completion can be enabled. When enabled, completion will let emacs complete partially typed names of interesting features like classes, interfaces, methods, etc. No longer do you have to type those 30 character interface names! Emacs does it for you! Do an emacs apropos search on "completion" (control-h 'a') for more information. Completion is normally mapped to meta-tab in most modes. (Completion can work even in text mode - it can complete from your local dictionary!)
• font-lock-mode. When Font Lock mode is enabled, text is fontified (i.e. put into new fonts, colors, styles, etc. depending upon what you are typing to make the display of information more clear) as you type it. While font locking can make for a more pretty/clear display, it can seriously slow down typing/development for large files and long-lived emacs sessions. Possible solutions include refining font locking (see turn-on-fast-lock and related functions), Lazy Font Locking (see lazy-shot-mode), caching font lock information (see fast-lock-cache-directories), and more.

References

These guidelines are based on example coding standards from several sources including, but not limited to:

• Doug Lea's Java Coding Standard - http://g.oswego.edu/dl/html/javaCodingStd.html.
• Scott Ambler's Java Coding Standards.
• Watts Humphrey's book A Discipline for Software Engineering, Addison-Wesley, 1995.
• Mark Fussell's Java Development Standards.
• The Coding Standards Repository for various languages.
• Coding Standards for C, C++, and Java by Vision 2000 CCS Package and Application Team.
• Kent Sandvik's Java Coding Style Guidelines
• Taligent's Java Cookbook for porting C++ to Java.
• Naval Postgraduate School Java Style Guide.
• Solo Software Engineering home page.