Java Style Guide

3BSE016637/-
 
Category: BU APS, BU MES
Draft

SUMMARY

This guideline gives recommendation for Java programming within ABB Automation and Drives.

The document is based on experiences made in BU MES in the US.

CONTENTS

1. INTRODUCTION 1.1 References 2. LANGUAGE ISSUES 2.1 General
2.2 Naming Convention
2.3 String Comparison
2.4 Collections
2.5 Systems Programming
2.6 Variables
2.7 Methods
2.8 Classes
3. FORMATTING ISSUES 3.1 Spacing
3.2 Comments
3.3 Automatic Document Generation from Comments via JavaDoc
3.4 Tagged paragraphs in Documentation Comments
3.5 Consistency
4. JAVA SOURCE CODE TEMPLATE

5. CONCLUSION


1. INTRODUCTION

This document gives recommendations of how to write programs in Java for applications within ABB Automation and Drives.

This style guide is not intended as a primer for the language; on the contrary, the reader should already be familiar with Java.

1.1 References

There are literally hundreds of books on Java, some more specialized than others, in any reputable book store, and the basics of the language can be learned from any one of them. To get the most up-to-date and comprehensive set of documentation anywhere, including "Frequently Asked Questions" and information about an authorized series of published books, visit http://java.sun.com/docs on the internet.
 

2. LANGUAGE ISSUES

2.1 General

    Choose names that are readable, descriptive, and clarify the objectís purpose.
       
    • Create names from words or phrases that are used in natural language.
    • Spell out identifiers completely, except for temporary local variables. Try to use a short full name or a well-accepted acronym instead of an abbreviation.
    • One of Javaís most significant differences from other object-oriented languages is its strong data typing. Because of this, cryptic name prefixes to indicate type and scope of variables are unnecessary and should be avoided.
    Instead of underscores, use upper case letters to begin new words in compound words, except where all caps are used (see below).

2.2 Naming Convention

    Begin with capitals for class names and class variables (static) and all caps for constants (i.e. final variables).

    Begin everything other than class names and class variables with a lower case letter. By convention, this includes class method names.

    Use the prefix "I" to differentiate an interface from a class.

    This is consistent with the class files that are auto-generated for COM interfaces by the ActiveX wizard or Jcom/Javac. Java class names are named "normally" however (without a "C" prefix) and the wizard (or you) will add the "C" for any COM-accessible coclass in the IDL definition, which also helps distinguish between the two different class files produced.

    Note, that interfaces are actually defined (i.e. coded) using IDL syntax and the resulting interface class files are then referenced (i.e. using the implements keyword) by Java class code.

2.3 String Comparison

    Probably the most insidious programming error in Java is to use string1 = = string2 to compare strings. This is is legal but checks for the same exact instance instead of the same character values. The desired action is usually string1.equals( string2 );

2.4 Collections

    Avoid modifying a collection while iterating over it and make a copy of a collection before iterating over it whenever it could be being modified by another thread.

2.5 Systems Programming

    Avoid the use of systems programming methods such as the java.lang.reflect package.

2.6 Variables

Variable names should be allowed the same simple set of rules as method names.
  • Name variables and methods so that their function is clear. Something referred to as aButton is clearly a temporary or local variable, yesButton() may access a member variable, but definitely returns "the instanceís yes button", and BigDialog.yesButton() accesses class data.
  • There are several reasons besides readability that special prefixes should not be used for variable names.
First, methods generally have a return type, but nowhere does anyone ever suggest that a method name should begin with a special prefix denoting what that type is. Also, if the object-oriented system of accessor methods is used as suggested by some Java books, the strangely named variables will only be accessed in two methods anyway. Yet another problem with type prefixing is that for non-primitive data types, some hard-to-read abbreviation must be concocted.
Variables should generally be declared private. Use accessors for getting and putting them.
This is for the same reasons as you would in any object-oriented language such as Java. It centralizes all accesses to a variable into a maximum of two methods. Even within the containing object, it allows easy adaptation to changes in representation and the underlying data structures.

The variables themselves should be declared private to control access. The use of the final modifier makes the variable access as efficient as accessing it directly (which has been documented as only a modest improvement, so do not use it religiously). Note, that if the method is to be private, it will automatically be final also, so final need not be specified.

The simplest convention for getting variables is using the variable name itself. This is not only less typing but should flow better when reading code. For methods that change variables, "put" as in putTheVarName(newVarValue) should be used.

It would be nice to have methods that change variables also overload the variable name itself, but with a parameter for the new value making the method signature different. However, that is not allowed in IDL so if the method is ever to be used in a COM interface, be sure to use the "put" format.

As with all methods, if accessors are to be used only by subclasses, they can be declared protected instead of public. And remember that the no-specification default is package access, which is actually closer to private than protected is.

Chain together simple method calls.  

This should actually be more readable than non-chained (assigning into temporary variables) simple method calls if proper naming is used, i.e. myEquipment.processQueue().size(). This is not to imply that it is good design practice to have one object know details of the implementation of another object, but that less coding is not necessarily more cryptic, and in fact sometimes, easier to read.

2.7 Methods

For readability, avoid using "this" wherever it is implied and could be omitted.
Example: doStuff instead of this.doStuff
Use predicate clauses or adjectives only for boolean objects or states.
Examples:
Use imperative verbs and phrases for methods which perform an action.
Examples:

2.8 Classes

      Avoid naming a class anything that implies how it is implemented.
      Using a physical name as opposed to a logical name may restrict future modifications of the class and limit its reuse.
      Define only one class or interface per Java source file, except for inner classes.
      Although multiples are allowed, this makes it much easier to answer the question, "Which file do I need to check out in order to make a change to this class?". Even if a class is not public, it is always visible to and usable by another class in the same package. Unlike C and C++ which allow objects to be used only from within a given source file, Java does not have a concept of private classes.
      Use inner classes whenever a class is needed for use only within a source file. These classes can easily access methods within an instance of their containing class without passing or using any explicit reference variables.

2.8.1 All classes should be declared to be in a package

For the mes platform the package will start with abb.mes, for example abb.mes.componentName.subComponent.etc. Additional classes created by BU MES centers may be placed in packages such as abb.metals or abb.mesMetals but the platform has claimed the basic short root name, abb.mes.
Because packages provide a unique name space, the actual class names can be made readable and fully descriptive without unnecessary acronyms and abbreviations. Some fully qualified class naming examples are:
abb.mes.system.GlobalObject
abb.mes.plant.
abb.mes.sched.
abb.mes.proc.SFCProcedure
abb.mes.proc.sfc.Step
Only a few Java classes will actually turn out to be COM coclasses, see COM guidelines for more information. For these "server" type classes, the fully qualified class name will make the actual Java implementation unique for those classes and the human-readable programmable ID should have a prefix in capitals. As in the examples above, the prefix is "MES." to make it unique. Example:
MES.PlantFactory
 

FORMATTING ISSUES

3.1 Spacing

    Employ a consistent spacing around methods and delimiters.

    Binary operators are easier to distinguish when separated from other programming constructs such as variables.

    Use a blank line to separate sections of code in a long method.

    Limit source code line lengths to standard workspace window widths.

3.2 Comments

      Do not comment one-liners or trivial methods such as simple accessors.

      Avoid relying on a comment to explain what is or could be reflected in the code.

3.3 Automatic Document Generation from Comments via JavaDoc

    The view that documentation is something that is added
    to a program after it has been commissioned seems to be
    wrong in principle, and counterproductive in practice.
    Instead, documentation must be regarded as an
    integral part of the process of design and coding.

    óC. A. R. Hoare, Hints on Programming Language Design (1973)

Use the /** format for comments that are to be automatically incorporated into documentation.
    1. <em> to start italicized text. </em> must be used to end the <em> section or all further text on the web page produced will appear italicized.
    2. <li> to start a new bullet line. </ul> must be used to end the <li> section.
     

3.4 Tagged paragraphs in Documentation Comments

For example, the @see tag can be used to create a link to specific methods or variables in other classes. However, do not bother using the @see tag to simply refer to a classís superclass because a link to that object is automatically generated in the HTML produced by the tool.
      1. @param paragraph

      2. A @param paragraph consisting of the name of a parameter followed by a short description should be included whenever the context of any parameter in a method needs more explanation.
      3. @return paragraph

      4. A @return paragraph consists of the name of the return value and a short description of the returned value. It should be included whenever the context of any parameter in a method needs more explanation.
      5. @exception paragraph

      6. An @exception paragraph should be included for every exception thrown by a method, even if it is a runtime exception that the compiler does not force to be declared. It consists of the name of an exception class (which may be a simple name or a qualified name) followed by a short description of the circumstances that cause the exception to be thrown.

3.5 Consistency

Use a consistent format throughout the Java source file
It seems that going along with the general format of items that are auto-generated by the Developerís Studio IDE wherever "acceptable" makes things look more consistent and causes the developer less trouble along the way.

For example, sometimes when the editor suddenly throws a tab into the code or removes one while you are typing, it is for good reason. Other times you need to go back and undo what it did because itís just not what you want.

JAVA SOURCE CODE TEMPLATE

    The following is the suggested template to base Java source files on. Note the // comments to help delineate the major types of items in the code as Javadoc automatically does in the documentation.
    package abb.mes.whatever;
    import java.util.*;
    import com.ms.com.*;
    import COM.objectspace.jgl.*;

    //
    //
    // TheClassName
    //
    //
    /** A summary sentence about the class goes here
    * <p> ç HTML marker needed to force new paragraph
    * More documentation comments about the class...
    * The symbol <em> "GoFast" </em> is important.  ç HTML markers used to highlight special text
    *
    * @version $Header$ ç Automatically puts info about source control version into source AND the JavaDoc
    * <p> Copyright 1998 ABB Industrial Systems Inc.  ç Must also put this in the version paragraph
    */

    public class TheClassName extends TheSuperclassName
    implements AnInterfaceName, AnotherInterfaceName

    {

    /** A summary sentence about instanceVar1 */
    private IUnknown instanceVar1;

    /** A summary sentence about instanceVar2
    * More documentation comments about instanceVar2

    */
    private String instanceVar2;

    /** A summary sentence about instanceVar3 */
    private HashTable instanceVar3;

        // CLASS VARIABLES

    /** A summary sentence about classVariable1 */
    private static int classVariable1;

    /** A summary sentence about classVariable2 */
    private static String classVariable2;

        // CONSTRUCTORS

    TheClassName ( int aParm )

    { super( aParm );               // Remember you can still use regular ç
    aClassMethod( aParm );         /* Non-Documentation comments like */
    }                               // these for the usual coding purposes

        // CLASS METHODS

    private static void aClassMethod ( int myParm )
    { classVariable1 = myParm;
    }

        // CONSTANTS

    public static final String MYCONST1 = "My string constant";
    public static final String UCONST2 = "Your string constant";

        // ACCESSORS

    public IUnknown instanceVar1()                ç remember the rule about NOT commenting
    { return instanceVar1; }                                 one-liners or trivial methods like these
    public String instanceVar2()
    { return instanceVar2; }    ç formatted to really be a one-liner for a quick read

    public void putInstanceVar2( String aParm )
    { instanceVar2 = aParm; }    ç in actual source editor font, repetetive nature of
    public HashTable instanceVar3()             ç name in the 2 lines makes this format easy to scan
    { return instanceVar3; }

        // INSTANCE METHODS

    //
    // other comments for more detailed grouping of methods, etc....
    //

    public IUnknown instMethod1()
    { putInstanceVar2( "abc" );
    putInstanceVar2( "xyz" );
    return instanceVar1().someMethod();
    }

    /** A summary sentence about instMethod2.
    *
    * @param argX some stuff that gets passed in
    * @param argY another param to test javadoc
    * @return This is the flag object that gets returned
    * @exception RuntimeException This one gets thrown when bad things happen
    * @exception ArithmeticException This gets thrown when good things happen
    */

    public boolean instMethod2( String argX, int argY )
    { putInstanceVar2( "abc" );
    putInstanceVar2( "xyz" );
    return instanceVar3() != null;
    }

    /** A summary sentence about instMethod3

    * More documentation comments about instMethod3

    */

    public void instMethod3()
    { };

    }

     

5. CONCLUSION

As stated previously, readability is one of the most important aspects of code maintenance. Even for the original author, it is easier to get back into the code when it has reasonable spacing and formatting, especially in a language that has the potential for being as cryptic as C.
 

 

REVISION 
Rev. Page (P)
Chapt. (C)
Description
Date
Dept./Init.
-
  Initial Version, based on document MES Java Style Guide. 1998-04-23 SEISY/LKD EdW