TPAE Java coding standard

This entry is part of the Maximo Java Development series.

What is a coding standard and why it is important?

A coding standard is a set of guidelines, rules and regulations on how to write code which will help developers quickly read and understand source code conforming to the style as well as helping to avoid introducing faults and misunderstanding.
Coding standards are important because they provide greater consistency and uniformity in writing code between programmers. This ultimately leads to the code that is easier to understand and maintain which reduces the overall cost of the project.

In this article I will go through some best practices that should be adopted when writing Java code within the TPAE framework.

Java Packages

Package names should be single lowercase words and must follow the existing format.
All packages containing custom classes must start with a common package that is unique to that TPAE instance. I typically use 'cust' as a general prefix or a short name (no more than 6 letters) of the customer.

For example, if you are extending the psdi.app.workorder.WO class, your custom class you should be cust.psdi.app.workorder.WO

The positive effect of this is that you can easily find all the custom code in your classes tree.
Here are some common examples of packages:

Java class type	Package	Directory
Business Objects (MBOs)	cust.app.xxx	[SPMDIR]\applications\maximo\businessobjects\classes\cust\app
Interface processing	cust.iface	[SPMDIR]\applications\maximo\businessobjects\classes\cust\iface
Maximo UI AppBeans and DataBeans	cust.webclient.beans	[SPMDIR]\applications\maximo\maximouiweb\webmodule\WEBINF\classes\cust\webclient\beans

Class Names

Classes should use natural descriptive names, begin with a capital, and have mixed case.
If you extend an existing Mbo you can use the same name as the base class.

package cust.app.asset;

public class Asset extends psdi.app.asset.Asset implements psdi.app.asset.AssetRemote
{
  ...
}

Alternative standard

Always prefix the class name with Cust whether creating a new or extending an existing one.

package cust.app.asset;

public class CustAsset extends psdi.app.asset.Asset implements psdi.app.asset.AssetRemote
{
  ...
}

Examples

CustMyTable
CustMyTableSet
CustMyTableRemote
CustFldMyTableMyField

NOTE: I personally prefer the other naming standard (without the Cust prefix) because the custom classes are already clearly separated from the standard ones using the package naming convention described above.

Code formatting

You have many 'religions' here. The most important thing is to be consistent.
Here is a sample of my preferred code formatting rules.

public void add() throws MXException, RemoteException
{
  super.add();

  MboRemote ownerMbo = getOwner();
  if (ownerMbo != null)
  {
    setValue("CREWCALNUM", "newval", NOACCESSCHECK|NOVALIDATION_AND_NOACTION);
  }
}

Don't criticize me I know it is not the 'standard' one :-)

Logging

Do not use SystemOut! Use the TPAE logging subsystem instead. Logger messages should have a well descriptive debug message.

MXLogger mxLogger = MXLoggerFactory.getLogger("maximo.application");
...
mxLogger.debug("This will be loged in SystemOut log file");

Comments

Class header
Insert a comment like this at the very beginning of all Java classes.

/*
 * Any copyright disclaimer
 *
 * Revision History
 * Change Date  Changed By        Request#      Comment
 * ----------------------------------------------------------------------------
 * YYYY-MM-DD   Bruno Portaluri   Defect 1234   Performance improvements
 *
 */

Class JavaDoc
Use JavaDocs comments and tags.

/**
* My version of Asset class.
*
* @author Bruno Portaluri
*/
public class Asset extends psdi.app.asset.Asset implements psdi.app.asset.AssetRemote
{
  ...
}

Method JavaDoc

/**
* Delete object and its childs.
*
* @param accessModifier Flag to bypass normal security checks.
* @return None
* @see #someOtherMethod
*/
public void delete(long accessModifier) throws MXException, RemoteException
{
  ...
}

Constants

Use constants in the psdi.mbo.MboConstants interface.
Since many base classes like psdi.mbo.Mbo and psdi.mbo.MboSet implements this interface, you can use this constantants without prefixing them with MboConstant.

The most important constants are listed below. Look at the complete list here.

DISCARDABLE - Bit for discardable mbos
NOACCESSCHECK - Suppress access control checks
NOACTION - Suppress action of a field
NOVALIDATION - Suppress validation of a field
REQUIRED - Set the field required

Example

setFieldFlag("siteid",READONLY, true);

Few other important constants are defined in psdi.webclient.system.beans.WebClientBean class.

EVENT_STOP_ALL - stops the current event and all other events in the EventQueue from being handled
EVENT_HANDLED - stops all other controls from handling the event
EVENT_CONTINUE - allows event to be handled by other controls

Annotations

@Override

Use it every time you override a method for two benefits.

Take advantage of the compiler checking to make sure you actually are overriding a method when you think you are. This way, if you make a common mistake of misspelling a method name or not correctly matching the parameters, you will be warned that you method does not actually override as you think it does.
Makes your code easier to understand because it is more obvious when methods are overwritten.

@Deprecated

If you want to remove an obsolete method that is called multiple times you could use the @deprecated annotation instead of deleting it. When you deprecate a method you should always explain in the annotation what is the new method to be called.

Labels: best practice, intermediate, java