Code Style

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

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.

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. As a result, the import part would look as follows: package

import all other regular or static imports

import javax.package.names import java.package.names

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

Indentation
Four spaces should be used as the unit of indentation.

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.

Comments
Java programs can have two kinds of comments: implementation comments and documentation (doc) comments.

Implementation comments are meant for comments about the particular implementation. Doc comments are meant to describe the specification of the code, from an implementation-free perspective. To be read by developers who might not necessarily have the source code at hand.

Comments should be used to give overviews of code and provide additional information that is not readily available in the code itself. Comments should contain only information that is relevant to reading and understanding the program. For example, information about how the corresponding package is built or in what directory it resides should not be included as a comment.

Discussion of nontrivial or non-obvious design decisions is appropriate, but avoid duplicating information that is present in (and clear from) the code. It is too easy for redundant comments to get out of date. In general, 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 drawn with asterisks or other characters.

Comments should never include special characters such as form-feed and backspace.

Code should not be commented out: delete the code instead. It will be available from the Git history if it is needed in the future.

Implementation Comment Formats
Programs can have four styles of implementation comments: block, single-line, trailing, and end-of-line.

Block Comments
Block comments are used to provide descriptions of files, methods, data structures and algorithms. Block comments may be used at the beginning of each file and before each method. They can also be used in other places, such as within methods. Block comments inside a function or method should be indented to the same level as the code they describe. A block comment should be preceded by a blank line to set it apart from the rest of the code.

codeGoesHere;

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

Single-Line Comments
Short comments can appear on a single line indented to the level of the code that follows. If a comment can't be written in a single line, it should follow the block comment format. Here's an example of a single-line comment:

if (condition) { /* Handle the condition. */   ifCode; }

Trailing Comments
Very short comments can appear on the same line as the code they describe but should be shifted far enough to separate them from the statements. If more than one short comment appears in a chunk of code, they should all be indented to the same tab setting. Here's an example of a trailing comment:

if (a == 2) { return TRUE;             /* special case */ } else { return isPrime(a);       /* works only for odd a */ }

End-Of-Line Comments
The  comment delimiter can comment out a complete line or only a partial line. It shouldn't be used on consecutive multiple lines for text comments. Usage examples: if (foo > 1) { // Do a double-flip. return bar.performDoubleFlip; } else { return false;                   // Explain why here. }

Documentation Comments
For further details, see How to Write Doc Comments for Javadoc which includes information on the doc comment tags @return, @param, and @see.

Doc comments describe Java classes, interfaces, constructors, methods, and fields. Each doc comment is set inside the comment delimiters, with one comment per class, interface, or member. This comment should appear just before the declaration:

/** * The ShinyBlock class provides the functionality ... */ public class ShinyBlock { ...

Note that top-level classes and interfaces are not indented, but their members are. The first line of doc comment  for classes and interfaces is not indented, but subsequent doc comment lines each have 1 space of indentation to vertically align the asterisks. Members, including constructors, have 4 spaces for the first doc comment line and 5 spaces thereafter.

If you need to give information about a class, interface, variable, or method that isn't appropriate for documentation, use an implementation block comment or single-line comment immediately after the declaration. For example, details about the implementation of a class should go in in such an implementation block comment following the class statement, not in the class doc comment.

Doc comments should not be positioned inside a method or constructor definition block because Java associates documentation comments with the first declaration after the comment.

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.

Deprecation
If you the  javadoc annotation, you must provide a comment, pointing the readers of code to the solution they should be using instead. See also an official guide on deprecation. Please note that the  annotation should always be present if the   javadoc tag is present, and vice-versa.

Number Per Line
One declaration per line is recommended since it encourages commenting. int level; // indentation level int size; // size of table

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[]; //WRONG!

Note: The examples above use one space between the type and the identifier. Another acceptable alternative is to use tabs: int    level;        // indentation level int    size;         // size of table Object currentEntry; // currently selected table entry

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

The one exception to the rule is indexes of for loops, which in Java can be declared in the  statement: for (int i = 0; i < maxLoops; i++) { ... }

Avoid local declarations that hide declarations at higher levels. For example, do not declare the same variable name in an inner block: int count; ... myMethod { if (condition) { int count = 0; ...   }    ... }

// AVOID!

Simple Statements
Each line should contain at most one statement. For example:

argv++;         // Correct argc--;         // Correct argv++; argc--; // AVOID!

Compound Statements
Compound statements are statements that contain lists of statements enclosed in braces. See the following sections for examples.


 * The enclosed statements should be indented one more level than the compound statement.
 * Open curly braces stay on the same line when statement fits there, otherwise moved to the separate line; the closing brace should begin a line and be indented to the same level as the beginning of the compound statement.

GTNH style overrides the Sun style which states: "The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement."

return Statements
A  statement with a value should not use parentheses unless they make the return value more obvious in some way. For example:

return; return myDisk.size; return (size ? size : defaultSize);

if, for, while Statements
The  code blocks should always be enclosed by curly braces. For simple single-line statements without, the curly braces can be omitted.

switch Statements
A  statement should have the following form:

switch (condition) { case ABC: statements; /* falls through */ case DEF: statements; break; case KLM: case XYZ: statements; break; default: statements; break; }

is indented on the same level as. Do not write unnecessary  and   when they can be avoided.

Every time a case has falls through (doesn't include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the /* falls through */ comment. Comment can be left off if there are no statements in the case that falls through.

GTNH Style overrides Sun's to not require break's or default when avoidable. The Sun guide states: "Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added."

Blank Lines
One blank line should be used in the following circumstances:
 * Between method declarations,
 * Between the local variables in a method and its first statement,
 * Before a block or single-line comment
 * Between logical sections inside a method to improve readability.

Blank Spaces
Blank spaces should be used in the following circumstances:

1. A keyword followed by a parenthesis should be separated by a space. For example:

while (true) { ... }

Note that a blank space should not be used between a method name and its opening parenthesis. This helps to distinguish keywords from method calls.

2. A blank space should appear after commas in argument lists. 3. All binary operators except "." should be separated from their operands by spaces. Blank spaces should never separate unary operators such as unary minus, increment ("++"), and decrement ("--") from their operands. Example:

a += c + d; a = (a + b) / (c * d);

while (d++ == s++) { n++; } printSize("size is " + foo + "\n");

4. The expressions in a for statement should be separated by spaces. Example:

for (expr1; expr2; expr3)

Casts should be followed by a blank space. Examples:

myMethod((byte) aNum, (Object) x); myMethod((int) (cp + 5), ((int) (i + 3)) + 1);

Naming
Naming conventions make programs more understandable by making them easier to read. They can also give information about the function of the identifier. For example, whether it's a constant, package, or class-which can be helpful in understanding the 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.

Referring to Class Variables and Methods
Avoid using an object to access a class (static) variable or method. Use a class name instead. For example:

classMethod;         //OK AClass.classMethod;  //OK anObject.classMethod; //AVOID!

Constants
Numerical constants (literals) should not be coded directly, except for -1, 0, and 1, which can appear in a for loop as counter values. Well-named constants should be used instead.

For example, instead of, the following is advised: int CONSTANT_NAME = 16281;

methodName(CONSTANT_EXPLANATION);

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

Do not use embedded assignments in an attempt to improve run-time performance. This is the job of the compiler. Example:

d = (a = b + c) + r;   // AVOID! // should be written as a = b + c; d = a + r;

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)    // AVOID! if ((a == b) && (c == d)) // RIGHT

Returning Values
Try to make the structure of your program match the intent. Example:

if (booleanExpression) { return true; } else { return false; } // should instead be written as return booleanExpression;

Similarly,

if (condition) { return x; } return y; //should be written as return (condition ? x : y);

Ternary Operator
If an expression containing a binary operator appears before the ? in the ternary ?: operator, it should be parenthesized. Example:

(x >= 0) ? x : -x;

Here are three acceptable ways to format ternary expressions:

// Single line alpha = (aLongBooleanExpression) ? beta : gamma;

// 2 lines with values lined up alpha = (aLongBooleanExpression) ? beta : gamma; //Multi-line with values lined up under condition alpha = (aLongBooleanExpression) ? beta : gamma;

Special Comments
Use the  in a comment to flag something that is bogus but works.

Use  to flag something that is bogus and broken.

stream API
Each  etc. method call should be placed on a new line.

collection.stream .filter(...) .forEach(...);

lambda Expressions
The simplest presentation should be used for lambda expressions:

.forEach(item -> System.out.println(item)); // not correct .forEach(System.out::println);             // correct

.forEach(i -> {                            // not correct i.doSomething; }); .forEach(i -> i.doSomething);            //correct

Inner Classes
The following rule is applied to the inner classes
 * 1) All inner classes should be placed in the end of the file by default
 * 2) The exception of the rule one could be used when:
 * 3) Inner class definition does not exceed 30 lines of code and
 * 4) The definitions of the methods that call inner class immediately follow after the inner class definition and take not more than 60 lines altogether.

Methods
The methods should be formatted in the following way: 1. When method declaration fits in 120 characters it should be written in single line:

public static String concat(@FunctionParameterName("value1")Any s1, @FunctionParameterName("value2")Any s2) { return s1.getValue + s2.getValue; }

2. When method is longer it should spread multiple lines with each line is no longer 120 characters. Line breaks should made after the coma or between annotations. It is recommended to minimize the number of lines by making lines as long as possible.

public static int countTradingDays(CoreApi core, @FunctionParameterName("fromDate")int fromDate,   @FunctionParameterName("toDate")int toDate) {   ... }

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