Java Coding Guidelines And Best Practices For Error-Free Code part 1 ~ foundjava

Presenting a detailed overview of Java coding guidelines to help programmers and automation testers. Whether you are into Java development or using Java for automation testing, you can use this post to improve your coding style. With the help of these Java coding guidelines, you’ll be able to write code which is robust, readable, rectifiable and reusable.

• Robust – Error-free and efficient.
• Readable – Easily read and understood.
• Rectifiable – Properly documented.
• Reusable – Capable of being used again.

Our objective is to provide a path to consistent practice while coding in Java language. These guidelines apply to all type of software coding activity using the Java language.

Java Coding Guidelines & Best Practices.

• File Structure for Java Source Files.
  • File naming guidelines.
  • Directory structure.
  • File structure.
• Class Structure for Java Source Files.
  • Class Header.
  • Static/Instance variable field declarations.
  • Static initializer.
  • Static member inner class declarations.
  • Method Declarations.
  • Instance initializer.
  • Constructor declarations.
• Naming Guidelines.
  • General concepts in Naming.
  • Article Naming Convention.
• Source Code Style Guidelines.
  • Line Spacing.
  • Blank Space.
  • If/else.
  • For.
  • While.
  • Do..While.
  • Switch.
  • Try/Catch/Finally.
• Comments.
  • Block Comments.
  • Trailing Comments.
  • Single Line comments.
  • Documentation comments.
• Standard Java Coding Conventions.
  • Declarations.
  • Statements.
  • Import Declaration.
  • Blank Spaces.
  • Indentation.
  • Continuation Lines.
  • Member documentation comments.
  • Class and instance variable field declarations.
• Exception handling.
• Eclipse Plugins for Code Styling.

1.1- File Structure For Java Source Files.

Let’s first go through what Java coding guidelines say about the file management.

1.1.1- File Naming Guidelines.

Java programs should use the following file suffixes.

File Type	Suffix
Java Source	.java
Class Files	.class
Archive Name	.jar or .zip

Note: Java source file name must be same as the class or interface name contained in that file.

1.1.2- Directory Structure.

Java

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

/***************** * Project Catalog: ***************** | | |------------- Docs => for project related document. | | |------------- Source => for all the source files. |          | |          |-------- packageA => for source files related to packageA. |          | |          |-------- packageB => for source files related to packageB. | | |------------- Target => for all the class files. |          | |          |-------- packageA => for class files related to packageA. |          | |          |-------- packageB => for class files related to packageB. | | ******* * Note: A file should contain only one public class in it. ******* */

1.1.3- File Structure.

As per Java coding guidelines, the project must include the following sections.

• File Header.
• Package Name.
• Imports.
• Class definition.

1.1.3.1- File Header.

Include a file header as provided below.

Java File Header.

Java

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

/***********************************************************************   #File header layout.     File Name         :   Principal Author      :   Subsystem Name        :   Module Name           :   Date of First Release :   Author :   Description           :       #Change History.     Version       :   Date(DD/MM/YYYY) :   Modified by :   Description of change :   ***********************************************************************/

1.1.3.2- Package Name.

Package names should occur on the first non-commented line of the source file and should follow the naming conventions defined in this document.

1.1.3.3- Imports.

Immediately following the package name should be the imported class names.

1.1.3.4- Class Definition.

Immediately following the imports should be the definition of the class. Organization of the class is described in the next section.

1.2- Class Structure For Java Source Files.

A Java class should comprise of the following sections.

1- Class Header.
2- Static/Instance variable field declarations.
3- Static initializer.
4- Static member inner class declarations.
5- Method declarations.
6- Instance initializer.
7- Instance constructor declarations.

Note: The class instance, static variables, and methods should fall in public, protected, default, and then private accessibility order. All public fields should have documentation comment.

1.2.1- Class Header.

The class header has to be included as given in below format.

Java Class Header.

Java

1 2 3 4 5 6 7 8 9

/** *    Java class layout. *    @deprecated * @see ClassName * @see ClassName#memberFunctionName * @version text * @author authorName *    @since */

1.2.2- Static/Instance Variable Field Declarations.

Static variables should come first and begin their declaration with the keyword <static>. Instance variables don’t require to get prefixed with the <static> keyword.

Example.

Java

1 2 3 4 5

static private int counter, serial; // Incorrect   static private int counter; // Correct   static private long serial; // Correct

Some of the important points you should note.

• Always get the field declarations in separate lines.
• A field or class which doesn’t change after initialization should be declared final. This approach allows the compiler to generate better code.
• Make sure to align the field names so that they all start in the same column.
• Don’t leave any variable without the access specifiers.

1.2.3- Static Initializer.

A static initializer, if any, comes next. It must have the following form.

Java

1 2 3 4 5

static {       statements;   }

1.2.4- Static Member Inner Class Declarations.

The inner classes which are static should come next. And such classes should follow the following structure.

Java

1 2 3 4

public class Outer {     static class Inner { // static inner class     } }

1.2.5- Method Declarations.

Every Java method should have linked description in <javadoc> format. Here is a <javadoc> sample to use for public methods.

Java Function Header.

Java

1 2 3 4 5 6 7 8 9 10 11 12

/** *    Description about the Method. *   *    @param name desc *    @exception name desc *    @return desc *    @see ClassName *    @deprecated * @version text * @author authorName *    @since */

Standard methods may avoid a description if grouped using any of the following logical groupings.

1- Factory
2- Private
3- Protected
4- Interfaces
5- Accessor
6- Temporal
7- I/O
8- Debugging

Example.

Java

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36

/* ======================================================= *      Factory Methods (usually static).   * ======================================================= */   /** brief summary.*/      public testClass initbject(void){ }     /* ======================================================= *      Accessor Methods.   * ======================================================= */      public int getObjectState(void);      public void setObjectState(int value);   /* ======================================================= *      Standard Methods.   * ======================================================= */      // anything it could be.   /* ======================================================= *      Debugging Methods.   * ======================================================= */      void doRunTests(void);

1.2.6- Instance Initializer.

An instance (non-static) initializer, if any, comes next.

1.2.7- Constructor Declarations.

Constructor declarations, if any, come next.

Example.

Java

1 2 3

public testClass();      public testClass(testClass source);

If there are multiple constructors and some have more parameters, then they should appear after those with fewer parameters. It means that a constructor with no arguments should always be the first one.

1.3- Naming Guidelines.

It’s one of the Java coding guidelines which depends on the context you are in. Let’s read more about this.

1.3.1- General Concepts In Naming.

1- Follow domain related naming strategy.
2- Use sentence case to make names readable.
3- Be reluctant while using abbreviations.
4- Prevent using redundant names that differ only in case.

1.3.2- Article Naming Convention.

1.3.2.1- Arguments Or Parameters.

Use a related name for the value/object being passed, and prefixing with <arg> or <param>.

e.g. argEmpName, paramSalary etc.

1.3.2.2- Fields And Variables.

Start field/variable name in lower case and then continue in sentence case.

e.g. clickCheckBox, viewInfo, openWindow.

Don’t use underscores to start or separate the words.

1.3.2.3- Constants.

Use upper case and underscores to form constants.

e.g. static final int MAX_SIZE = 256;

static final string BROWSER_TYPE = “Chrome”;

1.3.2.4- Classes And Interface.

Always begin class/interface names with a capital letter.

e.g. Class Name: PageFactory or PageObject.

Interface Name: IPageObjectModel

1.3.2.5- Compilation Unit Files.

Use the name of the class or interface prefixed with <.java> to represent it is a source code file.

e.g. TestPage.java, UIMap.java, LoginPage.java.

1.3.2.6- Component.

Use a meaningful name with a proper suffix.

e.g. categoryMenu, listView etc.

1.3.2.7- Packages.

Start package name with unique top level domain names like com, edu, gov, etc. Follow the ISO Standards 3166, 1981. Remaining part may vary according to an organization’s internal naming structure.

e.g. com.techbeamers.testpackage.