Code Style

This page describes the suggested Java Code Style for the development of GTNH.

Use automatic formatting provided by IntelliJ IDEA. It is available via a shortcut: Ctrl+Alt+L on Windows, L on macOS, or from the main menu: "Code > Reformat Code".

Introduction

Why Have Code Conventions

Code conventions are important to programmers for a number of reasons:

• For a piece of software, the vast majority of lifetime-cost goes to maintenance.
• Code is read more often than it's written.
• We have many developers working on the modpack. Consistent code style makes shared ownership easier.
• Code conventions improve the readability, allowing engineers to understand new code quicker and better.

Acknowledgements

This is intended to be a living document to be updated as the needs of the team change and as new language features are introduced.

The intention of this guide is to provide a set of conventions that encourage good code. It is the distillation of many combined man-years of software engineering and Java development experience.

While some suggestions are more strict than others, you should always practice good judgement.

If following the guide causes unnecessary hoop-jumping or otherwise less-readable code, readability trumps the guide. However, if the more 'readable' variant comes with perils or pitfalls, readability may be sacrificed.

In general, much of our style and conventions mirror the Code Conventions for the Java Programming Language. Other good references are Google's Java Style Guide and Twitter's Java Style Guide.

Recommended Reading

Good books for code style and conventions:

• Clean Code by Robert Martin,
• Effective Java by Joshua Bloch.

File Organization

A file consists of sections that should be separated by blank lines and an optional comment identifying each section. Files longer than 2000 lines are cumbersome and should be avoided.

Java Source Files

Each Java source file contains a single public class or interface. When private classes and interfaces are associated with a public class, you can put them in the same source file as the public class. The public class should be the first class or interface in the file.

Java source files have the following ordering:

• Beginning comments
• Package and Import statements
• Class and interface declaration(s)

Beginning Comments

Classes/Interfaces should be named well and in packages that provide context so a comment at the beginning of files giving a description of the class/interface is not needed.

Note: Do not use IDEA’s standard file comment’s templates. Your files should not mention IDEA (or other IDE). To set up file header, go to File > Settings > Editor > File and Code Templates | Includes | File Header.

Package and Import Statements

The first non-comment line of most Java source files is a package statement. After that, import statements can follow. For example:

package java.awt;

import java.awt.peer.CanvasPeer;

Imports should have separate section for java and javax, and mixed static (see below) and regular imports.

Static imports are not used with the following exceptions:

• Math.* if it's clear that numeric value passed as a parameter.
• java.util.stream.Collectors
• org.mockito.Mockito.* and org.mockito.ArgumentMatchers.* in tests

In tests, utility classes with assertion methods:

• org.junit.Assert
• org.hamcrest.Matchers, CoreMatchers, Matcher, MatcherAssert and alike
• org.junit.jupiter.api.Assertions and alike
• org.assertj.core.api.Assertions and alike

As a result, the import part would look as follows:

package

import all other regular or static imports

import javax.*
import java.*

Class and Interface Declarations

The following table describes the parts of a class or interface declaration, in the order that they should appear.

	Part of Class/Interface Declaration	Notes
1	Class/interface documentation comment (/**...*/)	Optional
2	class or interface statement
3	Class/interface implementation comment (/*...*/)	Optional. This comment should contain any class-wide or interface-wide information that wasn't appropriate for the class/interface documentation comment.
4	Class static variables	First the public class variables, then the protected, then package level (no access modifier), and then the private.
5	Instance variables	First public, then protected, then package level (no access modifier), and then private.
6	Constructors
7	Methods	These methods should be grouped by functionality rather than by scope or accessibility. For example, a private class method can be in between two public instance methods. The goal is to make reading and understanding the code easier.

Indentation

Four spaces should be used as the unit of indentation. Indentation should be achieved with the Tab symbol. The IDE should be set to force Tab to move cursor right 4 positions.

GTNH code style overrides the Sun style by stating Tab characters - Sun leaves it unspecified.

Line Length

Avoid lines longer than 120 characters, since they're not handled well by many terminals and tools.

GTNH Code Style overrides the Sun line length of 80 characters.

Wrapping Lines

When an expression will not fit on a single line, break it according to these general principles:

• Break after a comma.
• Break before an operator.
• Prefer higher-level breaks to lower-level breaks.
• Align the new line with the beginning of the expression at the same level on the previous line.
• After that, the break of the long code line to the to the next line is indented with the single (and not double) Tab
• The continuation on the next line shall be indented another single tab.

Here are some examples of breaking method calls:

someMethod(longExpression1, longExpression2, longExpression3,
    longExpression4, longExpression5);

var = someMethod1(tookWholeFirstLine,
    someMethod2(tookWholeSecondLine,
        longExpression3));

Following are two examples of breaking an arithmetic expression. The first is preferred, since the break occurs outside the parenthesized expression, which is at a higher level.

longName1 = longName2 * (longName3 + longName4 - longName5)
    + 4 * longname6; // PREFER
longName1 = longName2 * (longName3 + longName4
    - longName5) + 4 * longname6; // AVOID