Skip to content

CODE_STANDARDS.md

Latest commit

 

History

History
155 lines (95 loc) · 5.63 KB

CODE_STANDARDS.md

File metadata and controls

155 lines (95 loc) · 5.63 KB

Mongock Code Standard

Table of contents

Introduction

We use Google Java Style Guide as base guide, adding few rules.

Notice that as part of the code review sonarqube is used to check the code quality, which is configured with:

General

Column limit: 120

We add extra 20 characters to the goggle standard column limit: 120 characters column limit.

This is ok for most of screens and allow developers to split the screen in two, actual class and test.

Horizontal alignment: never required

Terminology Note: Horizontal alignment is the practice of adding a variable number of additional spaces in your code with the goal of making certain tokens appear directly below certain other tokens on previous lines.

This practice is NOT permitted by Mongock Style.

Here is an example without alignment, then using alignment:

private  int x;  // this is OK
private  Color color;  // this OK too

private  int   x;  // NOT allowed
private  Color color;

Access modifier

In this section we want to encourage the right modifier in every case.

  • package-private: The default modifier for classes and methods.
  • private: Default modifier for attributes and for methods accessed only but the current class.
  • protected: For members which are(or could be) accessed by children classes in a different package.
  • public: Only for classes, methods and static constants that are(or could be) accessed publicly.

Programming Practices

final modifier

You should be using final modifier for classes and members are instructed in the Java standard guide. In this section we add specific scenarios where you should be using final too.

  • Utility classes: In utility classes that are accessed statically.
  • Local variables: As general rule, use final in variables where reference is not intended to be modified. This helps readability.
  • Method parameter: Not required, but permitted, applying the rule for 'Local variables'

Immutability pattern

As part of this project we highly encourage immutability, so please apply it wherever is possible.

Java 8 Optional Vs null

As general rule avoid the presence of null references as much as possible. As returning type, use Optional as container type in any method where the returned object might be absent.

Generic

As part of this project we like to use meaningful type parameter names, although is opposite to the java standard. So this is not required, but appreciated.

Example:

public interface GenericInterface<GENERIC_PARAMETER> {
...
}

Code duplication

A maximum of 3% code duplication is allowed for new code.

Java 8 API

Use the Java 8 API where possible.

Test

Test file Naming

  • Unit tests: Unit test files must be named using the pattern *UTest.java
  • Integration tests: Integration test files must be named using the pattern *ITest.java

Method naming

Use the shouldXXX_whenXXX_ifXXXXX pattern for test names.

Example:

public shouldReturn4_whenSum_ifParametersAre2And2() {
...
}

Coverage

Any code delivered must be covered by unit and integrations test. We ensure this by using Jacoco plugin.

Coverage for unit and integrations tests are checked separately(both have 80% threshold coverage)

You can run the check simply by running mvn clean verify

Note: Please notice that when we you run jacoco(by mvn), it checks the entire project. However, the first thing we do when we perform a code review is to run sonar which checks that just the new code fits the coverage threshold. This means that when you verify locally you coverage, it passes, but it doesn't when we review. For this we suggest you make sure your new code fits the coverage threshold.

Javadoc

As part of this project we encourage self-explanatory code, so Javadoc is only required for public members which will be (or could be) used by the users of this library.

Where Javadoc required, we apply the Google style