Java Best Practices and Tips by Toptal Developers

As a part of the “fail fast” approach, public methods should always validate input parameters before executing any logic. This way, you avoid getting an error later, where the cause is harder to find.

Since version 1.4, Java has supported the assert keyword for this purpose. For example:

public void setAge(int age) {
    assert age >= 0 : "Age must be positive";
    …
}

An advantage of using assertions is that they can be disabled at runtime to avoid any performance impact in a production system.

Another approach is to use Google Guava, where you can use Preconditions class, which provides static methods. This way, you can get more accurate exceptions, as assertions throw only a generic AssertionError. The following example will throw an IllegalArgumentException:

public void setAge(int age) {
    Preconditions.checkArgument(assert age >= 0, "Age must be positive");
    …
}

In a similar way, you could use Preconditions.checkState(…) to validate post conditions, which throws an IllegalStateException. For a full list of precondition methods, check the Guava documentation.

Checking for parameter nullness is a particularly useful case for precondition validation. It is a good practice to check all the parameters that must not be null. Another good practice is to mark nullable parameters with javax.annotation.Nullable annotation. This way, your code is more readable. Adding Nullable annotation to methods that can return null values is also a good practice.

public void updateCustomer(int id, String name, @Nullable String address) {
    Preconditions.checkNotNull(name, "Name is mandatory.");
    …
}

If you are using Java 7 or beyond, you can use Objects.requireNonNull(…), which has the same functionality.

public void updateCustomer(int id, String name, @Nullable String address) {
    Objects.requireNonNull(name, "Name is mandatory.");
    …
}

Some simple recommendations to write better documentation:

• Write Javadoc comments for each public class and method (maybe setters and getters could be omitted).
• Avoid irrelevant and obvious comments. A comment saying “sets the name” on a setter provides no extra information.
• Explain the class purpose and its behavior.
• Explain the method contract and what is the expected behavior. Which input parameter values are valid? What values can be expected as output? Under which scenarios exceptions will be thrown? A good approach is to document pre and post conditions.
• Use meaningful, self-documenting names for classes, methods, and variables.
• Avoid unnecessary comments inside methods, especially since it’s too easy for comments and code to get out of sync with one another over time. If you write too many comments, maybe it is better to split the method into self-documenting private methods. For example, instead of adding a comment double finalPrice = price + (price * taxRate); // computes taxes, a better approach would be to create a private method, which is easier to read: double finalPrice = computeTax(price, taxRate);

Utility classes are classes that are not intended to be instantiated. Instead, they typically provide static methods for generic functionality, and they are like global functions in OOP. So, if you are writing too many utility classes, you should review your coding design. However, sometimes you will need to write some utility class, a good example being generic functions. Another example is internal Domain Specific Languages (DSL). When implementing a DSL in Java, you typically don’t follow OOP principles and write classes with static methods, since the goal is to make syntax shorter, rather than reusable components.

However, if you face a scenario where you prefer to write a utility class, consider the following recommendations:

• Make the constructor private. This way, the class can’t be instantiated.
• Make the class final. Even when a private constructor will restrict instantiation in subclasses, somebody could create a subclass and add more static methods.
• Create utility classes that are cohesive according to the functionality provided by their methods. Generic names like MvcUtils or CommonUtils usually lead to a bad design.

Reflection is a cool Java feature as it allows querying for class structure and dynamically making calls to methods, object instantiation, or setting field values. This feature is widely used in frameworks and libraries to build generic code that works in different classes.

Having the ability to execute code dynamically is powerful. However, if you use too much reflection in your code, you could jeopardize the code maintainability. Consider the following simple example: You need to copy fields from one Java Bean to another that has fields with the same name.

public class PersonEntity {
	private String firstName;
	private String lastName;

	public String getFirstName() {
		return firstName;
	}

	public void setFirstName(String firstName) {
		this.firstName = firstName;
	}

	public String getLastName() {
	return lastName;
	}

	public void setLastName(String lastName) {
		this.lastName = lastName;
	}
}

public class PersonDTO {
	private String firstName;
	private String lastName;

	public String getFirstName() {
		return firstName;
	}

	public void setFirstName(String firstName) {
		this.firstName = firstName;
	}

	public String getLastName() {
		return lastName;
	}

	public void setLastName(String lastName) {
		this.lastName = lastName;
	}
}

A viable option here is to iterate over getters and copy the values using reflection. For the sake of simplicity, I’m assuming that getters in the source object return exactly the same type as a setter in the target. Such an implementation could look like this:

public void copyWithReflection(Object source, Object target) throws 
		IllegalAccessException,
		IllegalArgumentException,
		InvocationTargetException,
		NoSuchMethodException,
		SecurityException {
	requireNonNull(source, "source can't be null");
	requireNonNull(target, "target can't be null");

	for (Method getter : source.getClass().getMethods()) {
		if (getter.getName().startsWith(GETTER_PREFIX)) {
			try {
			Method setter = target.getClass()
					.getMethod(SETTER_PREFIX + getter.getName()
					.substring(GETTER_PREFIX.length()),
							getter.getReturnType());
			setter.invoke(target, getter.invoke(source));
			} catch (NoSuchMethodException e) {
				// Nothing to do, setter does not exist.
			}
		}
	}
}

At first sight, this seems like a good idea. You can use the same logic for copying values in different classes. But what happens if, in the future, you need to copy only some fields? A viable option here is to add annotations to getters, but that would add unnecessary complexity. Even worse, what happens if in the future you need some type of data conversion? What happens if you change a field in the source, but you forget to add it to the target?

Probably a better and simpler approach would be just copying properties explicitly:

public void copyWithoutReflection(PersonEntity source, PersonDTO target) {
	target.setFirstName(source.getFirstName());
	target.setLastName(source.getLastName());
}

This approach has the advantage of being simpler, more readable, deals with fewer exceptions and maintains compile-time checking for method names. And it is more flexible since getters and setters don’t need to have the same name.

First generation dependency injectors, such as Spring, used XML-based configuration plus reflection to set-up components, thus losing compile-time type checking. Later, more advanced injectors such as Guice and Dagger added Java-based configuration, to add more compile-time checking, but the reflection was still used. Dagger 2 utilizes a 100% code generation based approach, eliminating the need for reflection and providing compile time validations for injector set-up.

When you add two string in a loop (for, while, do-while), concatenating them using the + operator causes wastage of memory and increases performance time. This is because a new String Object is created each time a new String is added. Instead, the best practice is to use a StringBuilder class.

Let’s show it with the examples:

//Bad Practice
String output = "";
for (String s : largeArray) {
    output = output  + s;
}

If we add this Java snippet to the bytecode and then the generated bytecode decompile back, we will get the following code:

String output = "";
for( String s : largeArray ) { 
    output = new StringBuilder().append(output).append(s).toString(); 
} 
return output;

As we can see, Java used an internal StringBuilder, and in the loop, two operations are executed each time.

So, a much better solution would be to use a StringBuilder in the first place:

//Best Practice
StringBuilder sb = new StringBuilder();
for (String s : largeArray) {
    sb.append(s);
}
String output = sb.toString();

To confirm this, I tested both scenarios (i.e., using the ‘+’ operator plus the StringBuilder). Here are the results:

Testing PC:

• Intel Core i5 M 540 @ 2.53GHz
• 8GB RAM
• Windows 10 Pro
• Java 1.8

As we can see, the results confirm the original assertion.

To learn more, Laurent gave a detailed explanation of the process using the disassembled bytecode in Java 8.

Java, as a strongly typed language, provides a generic type system. Designing how your classes will make use of generic types could be hard and tedious, but it offers significant advantages. The resulting code is cleaner since you will no longer need most cast operations. Also, the code will be safer, since more type validations will be done at compile time, thus avoiding ClassCastException errors at runtime.

But, as said before, generic types could be complicated. As generics is a big topic, reading additional Java documentation is a good idea.

Dealing with the Invariant Nature of Generics

Let’s start explaining the meaning of variance. In object-oriented (OO) programming, it is natural to think of superclasses as more generic types than subclasses. We can think of superclasses as “bigger” types since they could include more classes than specific subclasses. For example, java.lang.Number, could be considered as a bigger type than java.lang.Integer, since it can also contain java.lang.Double, java.lang.Float, and so on.

While this is quite simple in the standard OO inheritance, it could become a little harder when dealing with more complex type systems, such as the one defined by Java generics. Specific concepts needs to be defined to specify which type is bigger than the other.

According to Wikipedia, four categories can be used: * Type A is covariant to B if A >= B. This mean, a variable of type A can hold instances of B. * Type A is contravariant to B if A <= B. This is almost the opposite to previous point. * A type is bivariant if it is both covariant and contravariant at the same time. This is not supported by Java. * A type is invariant if it does not fit on any of the previous definitions.

In Java, generics are invariant by default (in contrast to arrays, which are covariant). This kind of incoherence can lead to confusion. For example, this code is valid in Java:

String stringArray[] = { "Hi", "how", "is", "it", "going?" };
Object objectArray[] = stringArray;

To explain this a bit: String[] is a subtype of the Object[]. The problem with this approach is that it could lead to runtime exceptions. For example, executing the following line will produce an java.lang.ArrayStoreException exception:

objectArray[0] = 123; 

To avoid this, generics types are not covariant by default and, this way, the compiler can prevent these kinds of errors. The following code will produce a compile-time error on the second line:

List stringList = new ArrayList<>();
List