elastic-db-tools-for-java/Coding_Guidelines.md

Java Coding Standards

The purpose of the Java Coding Standards is to create a collaboration baseline. It will be helpful for scenarios where many people are creating, modifying, and contributing to the same project.

0. Use Wisely

Do NOT blindly obey these guidelines, use them (after understanding) where they make sense.

1. General

All changed code, must obey these coding standards. As we have huge legacy code we will have code which defers Coding Standards. Eclipse code formatter mssql-jdbc_formatter.xml must be used to format the changed code, except for enum types.

2. Comments

We should give appropriate java comments in code. Please find ideal example of java comments. We do not expect to have full javadocs for common methods like getters / setters.

Correct:

/**
 * Get property-only names that do not work with connection String
 * 
 * @param name
 *            to normalize
 * @param logger
 * @return the normalized property name
 */
static String getPropertyOnlyName(String name, Logger logger) {
	if (null == name) {
		return name;
	}
	... some complex logic
}

Incorrect:

 // Get property-only names
  static String getPropertyOnlyName(String name, Logger logger) {
 	if(null == name) {
		return name;
	}
	...
 }

3. Copyrights

All Java files should contain the appropriate copyright notice at the beginning of the file.

/*
 * Elastic database tools for Azure SQL Database.
 * 
 * Copyright(c) Microsoft Corporation All rights reserved.
 * 
 * This program is made available under the terms of the MIT License. See the LICENSE file in the project root for more information.
 */

4. Good Practices

Pay special attention to the most common style errors...

• classes too long
• methods too long
• little or no javadoc comments
• swallow exceptions
• multiple return statements
• Overuse of arrays in place of collections
• too much or no whitespace

4.1. Avoid multiple return statements

Multiple return statements are hard and time consuming to debug.

Correct:

 public class StringUtils {

 	public static boolean isEmpty(String string) {
 		return string == null || "".equals(string.trim());
 	}

 }

or

public class StringUtils {

 	public static boolean isEmpty(String string) {
 		boolean empty = false;
 		if (string == null) {
 			empty = true;
 		} else if ("".equals(string.trim())) {
 			empty = true;
 		}
 		return empty;
 	}

 }

Incorrect:

 public class StringUtils {

 	public static boolean isEmpty(String string) {
 		if (string == null) {
 			return true;
 		} else if ("".equals(string.trim())) {
 			return true;
 		}
 		return false;
 	}

 }

4.2. Boolean comparisons

Mirroring the natural language "if the current state is not active" rather than "if active is not the current state"

Correct:

	!active

Incorrect:

	active == false

4.3. for loops Vs for-each loops

When iterating over iterable elements where the current index in the iteration is not important for-each loops are preferred. **Not compatible for JDK 1.4 **

Correct:

	for (String name: names) {
		doStuff(name);
	}

Incorrect:

	for (int i = 0; i < names.length; i++) {
		doStuff(names[i]);
	}	

4.4. String concatenation

Avoid the use of + or += to concatenate strings. Use java standards designed for that purposes such as String.format, StringBuilder, etc. If you are doing thread safe operation then use StringBuilder instead of StringBuffer.

Correct:

	log.debug(String.format("found %s items", amount));

Incorrect:

	log.debug("found " + amount + " items");	

4.5. Collections

Use the right collections for the right task.

Duplicates

• Allows duplicates: List
• Does Not Allow Duplicates: Set, Map

Implementations Iteration Order

• HashSet - undefined
• ConcurrentHashMap - undefined
• HashMap - undefined
• LinkedHashSet - insertion order
• LinkedHashMap - insertion order of keys
• ArrayList - insertion order
• LinkedList - insertion order
• TreeSet - ascending order (Comparable / Comparator)

4.6. Raw types

Avoid using raw types when using classes that support generics.

Correct:

List<String> people = Arrays.asList("you", "me");

Incorrect:

List people = Arrays.asList("you", "me");

5. Design Patterns

Consider the use of common design patterns.

5.1. Enums

Constrain arguments by using type safe enumerations.

Correct:

public enum Options {
	YES, NO
}

Incorrect:

String yes = "YES";
String no = "NO";

enum value with multiple constants must be alligned such that the constant of same type from all the values must be alligned in same column.

Correct:

public enum SqlType{
	VARCHAR 	("varchar",		JDBCType.VARCHAR),
	NVARCHAR	("nvarchar",	JDBCType.NVARCHAR),
	CHAR		("char",		JDBCType.CHAR);
}

Incorrect

public enum SqlType {
	VARCHAR("varchar", JDBCType.VARCHAR),
	NVARCHAR("nvarchar", JDBCType.NVARCHAR),
	CHAR("char", JDBCType.CHAR);
}

5.2. Private Helpers

Consider private helper methods to break down complex flows and long methods into more readable code.

6. Active enforcement

Java developers are expected to use tools that enforce some of these good practices and quality code in general.

• The de-facto Editor is the Eclipse IDE
• New developed code should pass SonarQube rules
• Strongly recommend Sonar Lint tool
• New developed code / Only changed code should be formatted by Eclipse formatter.