Coding Standards

The document outline some coding standard and best practices taken from all over the interwebs. Some are copied from other source directly, some are copied with some rewording.

General Convention

1. Always use standard Java naming conventions

• • Read and always follow the basic java coding conventions outlined in this Code Conventions for the Java ™ Programming Language

Writing Code

1. Always pay attention to all warnings

• • Most modern IDE will warn you of ill formed code statements. Always pay attention to this warning and try minimize this warning to as minimal as possible.

double d = 5;
// modern IDE will warn you about this bad code construct!
Double anotherDouble = Double.valueOf(d);

2. Document public classes, public properties and public methods

• • Try to add brief description of the rationale for every class. If possible put example of how the class can be instantiated and used in the client code (dynamically injected by Spring, instatiate using new operator, static method returning the class object, singleton access, utility access).
  • Try to add brief description of what the general behavior of each public methods. The description should include allowed inputs, expected outputs, and exceptions that will be thrown by the methods.
  • Always state the expected output in the case where the output will be either empty list or null object.

3. Write unit tests

• • Every public method should have corresponding unit test for every potential branch inside the public method. For example you can use clover to see the coverage of unit tests against the code!
  • Every public method should have @should annotation. This annotation will be read by the behavior test generator plugins. This plugin will automatically generate unit tests stub for you!
  • The @should must be followed by the expected behavior of the method that will be tested in the corresponding unit test.

Naming Convention

1. Never redefine and wrap known classes

• • Redefining class with the same name might lead to confusion as to which class is being referred.

//it is not ok to reuse/redefine the class String:
class String {
	private final java.lang.Strings;
	public String(java.lang.Strings) {
		this.s = s;
	}
	public java.lang.String toString() {
		returns;
	}
}
class StringConfusion {
	public static void main(String[] args){ //not the correct main method
		String s = new String("Helloworld");
		System.out.println(s);
	}
}

2. Always use standard Java naming conventions

• • Pick descriptive and meaningful name for all classes, properties and methods. Descriptive and meaningful name doesn't have to be a very long name which would end up confusing the other team member.

// bad naming
public MyClassToHoldClassCounter {
	...
}
// better naming
public ClassCounter {
	...
}

Package, Class and Interface

1. Always use explicit import statements

• • Avoid using the wildcard import statement. Instead list all classes in the import statement. Explicit import statement help maintainer of the code to understand the precise list of dependency of the code. This makes it easier to understand how dependent a class is on other classes (the higher dependency, the more complex the class).

2. Obey the contracts for equals(Object o)

• • When overriding the equals() method, one should ensure that it is:
    • reflexive: x.equals( x ) for all non-null objects x
    • symmetric: x.equals( y ) implies y.equals( x ) for all non-null objects x and y
    • transitive: x.equals( y ) and y.equals( z ) implies x.equals( z ) for all non-null objects x, y and z null
    • sensitive: x.equals(null) == false for all non-null objects x
    • consistent: x.equals( y ) should stay constant if no changes are made to x and y for all non-null objects x and y

3. Define both equals(Object o) and hashCode()

• • If you define equals(Object o) then you must define hashcode() and vice versa.
  • The following property should be satisfied when defining these two methods. For two given objects o1 and o2 o1.equals(o2) implies o1.hashCode() == o2.hashCode()
  • Similarly, if compareTo(Object o) is overridden, then also equals(Object o) (and consequently hashCode()) should be. That is, the following contract should be satisfied:o1.compareTo(o2) == 0 if and only if o1.equals(o2)