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.

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, 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.

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 ...   } }

switch Statements
It is suggested to use the following form: switch (condition) { case ABC, DEF, KLM -> { statements; }   case XYZ -> { statements; }   default -> { statements; } }

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

Providing Access to Instance and Class Variables
Don't make any instance or class variable  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, 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!

Do not use the assignment operator in a place where it can be easily confused with the equality operator. Example:

if (c++ = d++) {        // AVOID! (Java disallows) ... } // should be written as if (c = d++) != 0) {   ... }

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 params) { // }

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!