Source file

File name

Java source file name must be equivalent to top-level class name + '.java' extension. This rule does not work for package-info java source files, in this case file must be named as package-info.java.

Allowed:

// file name Example.java

class Example {}

// file name is package-info.java

/**
* Package classes documentation.  
*/
package com.codenvy.api.workspace;

Not Allowed:

// file name is Example.java
// file name does not match class name

class NotExample {}

// file name is PackageInfo.java
// wrong file name for package-info(must be package-info.java)

/**
* Package classes documentation.  
*/
package com.codenvy.api.workspace;

File encoding

File encoding is UTF-8

Special characters

Whitespace characters

There are only 2 types of whitespace characters which are allowed to use in source file content:

1. Space (0x20)
2. Any line separator sequence (0x10 0x13, 0x10, 0x13)

Tab character is not used

Tab character is not used for indentation, spaces are used instead. See indentation section.

Non-whitespace characters

• For characters which have escape sequence (\b, \t, \n, \f, \r, ", ', \) that sequence should be used rather than the same octal or unicode escape.

// Good
String line = "Name:\tAge:\n\'John\'\t21";

// Bad, octal escape is used for '\t', ''', '\n'
// it is not readable and confusing
String line = "Name:\011Age:\012\047John\047\01121";

• For other characters which are Non-ASCII such as λ or β - unicode character is preferable to unicode escape as it almost always says everything about this character, but unicode escape may be used as well in this case. When unicode escape is used it should be commented.

// Good
String f = "λ = G/m"; // Lambda = Heat/Mass  

// Worse, lambda character should be used instead of unicode escape
String f = "\u03BB = G/m"; // Lambda = Heat/Mass  

// The worst, neiter comment no unicode character is used for the lambda
String f = "\u03BB = G/m";

Source file structure

• Copyright (optional)
• Package
• Imports
• Top-level class

Copyright

If copyright belongs to file it must be placed exactly above package declaration. No empty lines allowed between copyright and package declaration.

Package statement

Package statement must be defined in a single line, also package statement must be followed with exactly one empty line.

//Allowed
package com.codenvy.api.workspace;

//Not allowed, should be defined in a single line
package com.codenvy
           .api
           .workspace;

Imports

• Wildcard imports are not allowed
• Each import must be defined in a single line
• Imports must be grouped
  • Group for static imports
  • Group for java.* imports
  • Group for javax.* imports
  • Group all other imports by top level package name
• Each group must be followed by exactly one empty line.
• ASCII sort order is used inside of groups
• Import groups order
  • Third-party import groups such as org.eclipse.che.*
  • javax.* imports group
  • java.* imports group
  • Static imports group

Allowed:

import org.eclipse.che.api.core.ConflictException;
import org.eclipse.che.api.core.ForbiddenException;
import org.eclipse.che.api.core.NotFoundException;
import org.eclipse.che.api.core.ServerException;
import org.eclipse.che.api.core.rest.Service;

import javax.inject.Inject;
import javax.ws.rs.Consumes;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;

import static java.util.Arrays.asList;
import static java.util.Collections.singletonMap;
import static javax.ws.rs.core.MediaType.APPLICATION_JSON;

Not Allowed:

// There are 3 groups of imports
// 1 - java.*
// 2 - javax.*
// 3 - static group
// according to the rules it should be separated with empty lines +
// javax imports should appear before the java imports

import java.util.ArrayList;
import javax.inject.Inject;
import static java.util.Arrays.asList;

// static import should be declared in a single line
import static java.util
                  .Arrays
                  .asList;

Class declaration

• Source file must contain exactly one top-level class
• Class members ordering is not required except of methods or constructors with the same name.