Code Style

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

Introduction

Code conventions are important 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 the development easier.
• Code conventions improve the readability, allowing developers to understand Pull Requests quicker.

The purpose of this Code Style is to provide a set of conventions that encourage good code.

Always practice good judgement. If following the guide causes unnecessary hoop-jumping or less-readable code, then readability trumps the guide. However, if the more "readable" variant comes with perils or pitfalls, then readability may be sacrificed.

In general, much of this Code Style is a summary of the Code Conventions for the Java Programming Language. Other good references are Google's Java Style Guide and Twitter's Java Style Guide.

Good books for code style and conventions:

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

Spotless

GTNH uses Spotless to check line wrapping, spacing, and indentation.

File Organization

Files longer than 2000 lines are cumbersome and should be avoided.

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 public class variables, then protected, then package level (no access modifier), and then private.
5	Instance variables	First public, then protected, then package level (no access modifier), and then private.
6	Constructors
7	Methods	The 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.

Comments

• Usually, code should not be commented out – delete it instead. If the code needed again, it will be available in the Git history.
• Avoid any comments that are likely to get out of date as the code evolves.
• The frequency of comments sometimes reflects poor quality of code. When you feel compelled to add a comment, consider rewriting the code to make it clearer.
• Comments should not be enclosed in large boxes of asterisks or other characters.

Comment Styles

A single-line comment can use a double-slash notation:

if (foo > 1) {
    // Do a double-flip.
    return bar.performDoubleFlip();
}

If the comment spans multiple lines, then convert it to a block-comment:

codeGoesHere();

/*
 * Here is a block comment.
 */
moreCode();

Authorship

Usage of @author tag is neither required, nor prohibited. Keep in mind that version control system already has the always up-to-date information about the people who worked on a given piece of code.

Declarations

Number Per Line

Multiple declarations per line can be the best course of action only of the variables are strongly connected. For instance, if they are 3D coordinates:

int x, y, z;

Do not put different types on the same line. Example:

int foo, fooarray[]; // AVOID!

Initialization

Try to initialize local variables where they're declared. The only reason not to initialize a variable where it's declared is if the initial value depends on some computation occurring first.

Placement

Put declarations only at the beginning of blocks. A block is any code surrounded by curly braces "{" and "}". Don't wait to declare variables until the first use -- it can confuse the unwary programmer and hamper code portability within the scope.

void myMethod() {
    int int1 = 0;      // beginning of method block

    if (condition) {
        int int2 = 0;  // beginning of "if" block
        ...
    }
}

Statements

switch Statements

It is suggested to use the following form:

switch (condition) {
    case ABC, DEF, KLM -> {
        statements;
    }
    case XYZ -> {
        statements;
    }
    default -> {
        statements;
    }
}

To use it, enable modern java syntax as shown in the ExampleMod.

Naming

Below is the table about most important naming conventions in the GTNH pack for the new code:

Identifier type	Rules for Naming	Examples
Classes	Class names should be nouns, in mixed case with the first letter of each internal word capitalized. Try to keep your class names simple and descriptive. Use whole words-avoid acronyms and abbreviations unless they are widely used.	class Raster class ImageSprite
Interfaces	Interface names should be capitalized like class names.	interface RasterDelegate; interface Storing;
Methods	Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized.	run(); getBackgroundColor();
Variables	Variables should be named as mixed case with a lowercase first letter. Internal words start with capital letters. Variable names should always start with an alphabetic character not underscore _ or dollar sign $. Variable names should be short yet meaningful. The choice of a variable name should be designed to indicate to the casual observer the intent of its use.	String currentAccountKey;

GTNH-specific

Log formatting

For uniformity, most of log messages should use one write-call per line. One-sentence messages should not be capitalized. If there is more than one sentence, then capitalize.

Programming Practices

Providing Access to Instance and Class Variables

Don't make any instance or class variable public without good reason. Often instance variables are set or obtained as a side effect of method calls instead of being accessed directly.

Constants

Constants should not be coded directly. Please use well-named constants instead.

For example, instead of methodName(16281), the following is advised:

int CONSTANT_NAME = 16281;

methodName(CONSTANT_NAME);

Variable assignments

Avoid assigning several variables to the same value in a single statement. It is hard to read. Example:

fooBar.fChar = barFoo.lchar = 'c'; // AVOID!

Deprecation

When using annotation @Deprecated, you must provide a comment referencing the solution that should be used instead. The @Deprecated annotation should always be present if the @deprecated javadoc tag is present, and vice-versa.

/**
 * @deprecated use {@link DBHelper#update(java.lang.String, java.util.Map)}
 */
@Deprecated(forRemoval = true)
public int insert(String request, Map<String, ?> params) {
    // <existing code>
}

Miscellaneous Practices

Parentheses

It is generally a good idea to use parentheses liberally in expressions involving mixed operators to avoid operator precedence problems. Even if the operator precedence seems clear to you, it might not be to others-you shouldn't assume that other programmers know precedence as well as you do.

if ((a == b) && (c == d)) // OK
if (a == b && c == d)     // AVOID!