...
Java coding guidelines are largely based on SUN official Java coding conventions: https://www.oracle.com/technetwork/Java/codeconvtoc-136057.html. Below are the only exceptions, clarifications, and additions to this standard that are specific to Apache Ignite development process.
Rationale
Studies have shown that 80% of development time is spent on software maintenance, which involves software source code understanding, refactoring, and support. Established and enforced code formatting rules and guidelines improve source code readability, promote team code ownership, allow engineers understand new code more quickly and thorough as well as simplify maintenance.
...
Use a shortened form of boolean expression where it does not compromise the readability.
Use a shorter form of "callbacks" are allowed now where it does not compromise the readability:
...
Except for types (classes, interfaces, enumerations and annotations) and semantic constants names, all other names should start with a low-case letter. Types names should start with an upper-case letter. In the both cases, a camel style should be used. Symbol '_' (underscore) should be used only to separate upper-case letters in the names. Constants (final class attributes that have constant semantic and are not just made final because of inner class access or performance considerations) should all be upper-case. For example (class comments ommittedomitted):
Code Block | ||||
---|---|---|---|---|
| ||||
class Window implements ScreenObject { /** */ private static final int MAX_INDEX = 10; /** */ private int currIndex; /** */ private int serialUid; /** * @param uid UID. * @return Class name. */ public String classNameByUid(Long uid) { . . . } } |
...
Types and methods names are NOT abbreviated except for well-known cases such as EOF, Fifo, etc. See Abbreviation Rules for a list of currently accepted abbreviations.
...
K&R bracing and indentation style should be used. { starts on the same line as the opening block statement. For example:
...
Braces are required in all cases, even if not required by syntax, except for the cases when the next statement is a one-liner. For the latter, braces must not be used, e.g.:
...
4-space characters should be used for both tabulation and indentation.
When a multi-line operator (try-catch, anonymous class instantiation, etc) goes after some condition it is required to use braces:
...
All javadoc commetns comments should be approximately 80 characters long. Always keep in mind that we create Javadoc for people to read - it should be easy to consume and easy to understand.
...
Every type should start with at least minimal Javadoc comments including a description in the following form:
...
NOTE: multiline comments in Javadoc tags should be indented by 4 or 5 characters depending on the configuration of IDE. In most IDEs the single TAB click will produce only 1 character identation indentation which is not enough for readability. Second The second click on TAB will shift it to (1+4) 5 characters. This is the only exception from 4-characters tabulation rule.
It is ok to have empty (/* /) or auto-generated Javadoc comments for code elements that are "work in progress". However, it is not allowed to not have a Javadoc comment at all, i.e. every field, method, initializer or type regardless of visibility scope should have at least empty Javadoc with minimally required Javadoc tags (see above).
Description The description must be separated by one blank line from Javadoc tags.
...
All comments should follow English grammar and punctuation including starting with an upper-case letter and ending with '.'. No technical jargon is allowed in the comments.
...
Code Block | ||||
---|---|---|---|---|
| ||||
public void foo( Object obj1, Object obj2, ... , Object objN ) |
Mixing declaraion declaration styles is not allowed.
...
In comma-separated enumerations, there is always a space between the comma and the next element in the list. For example, foo(p1, p2, p3) Notice spaces between comma ',' and the next parameter.
There is always a space in between operands and the binary operation itself. For example:
...
Static imports should follow same rules as regular imports and be separeted separated by a new line.
Code Block | ||
---|---|---|
| ||
import java.util.ArrayList; import java.util.Collection; import org.apache.ignite.lang.IgniteUuid; import org.apache.ignite.thread.IgniteThread; import org.jsr166.ConcurrentHashMap8; import static java.util.concurrent.TimeUnit.MILLISECONDS; import static org.apache.ignite.events.EventType.EVT_NODE_FAILED; import static org.apache.ignite.events.EventType.EVT_NODE_JOINED; import static org.apache.ignite.events.EventType.EVT_NODE_LEFT; |
...
The source code should be broken into minimal semantic units and all such units must be separated by one empty line. To simplify the recognition of semantic units, the every line of the source code should be separated by one empty line except for the following cases:
...
Source code line should not be longer then than 120 characters (to be visible on most conventional monitors). 4 space characters should be used for tabulation and indentation. IDE should be configured to replace tabulation with spaces (to properly see source code on the platforms with different tabulation sizes).
Empty lines should be used according to the following rules:
Where | Number of empty lines required |
---|---|
Before package statement | 0 |
Before imports | 1 |
Between imports and static imports | 1 |
Before class header | 1 |
After class header | 0 |
Between class definition and EOF | 1 |
Between class members (fileldsfields, methods, initializers) | 1 |
Between minimal semantic units in the method or initializer body | 1 |
...
Blanks space (1 space character) should be used before opening ( or {. { and } should always be the last tokens in the line (except for the possible comments). However, blank space should not be used between the method name and opening (.
...
If source code lines and/or Javadoc lines get longer than 120 characters it should be broken. The rule is to start consequent line 4 spaces to the right relatively relative to the first line. All other lines 3rds, 4th, etc. (if the overall line gets longer than 120x2) should start on the same indentation as 2nd line. No other decorative rules are allowed.
In other words, the current line should never be indented more then than 4 spaces to the right from the previous line.
...
Code Block | ||||
---|---|---|---|---|
| ||||
throw new CacheException("Invalid type [type=" + type + ", xid=" + tx.getXid() + ']'); throw new WorkflowException("Invalid rule: " + rule.getName()); |
Note that all prefixprefixes, postfix, name, value postfixes, names and values should follow English grammar, in particular, start with upper case and end with the dot '.'.
...
Java 5 added many additional useful features that significantly improve the quality of code.
...
Stream API is convenient means of data processing but usages usage of this API should be avoided in most cases because it can lead to unpredictable and uncontrolled creation of class instances and therefore create additional pressure on GC.
...
When the correctness of code depends on some preconditions or expectations (including values of the call arguments) they should be expressed explicitly using assert statements. In public API methods, functions from GridArgumentCheck class should be used for argument check instead of assert.
...
Code Block |
---|
// TODO: IGNITE-xxx, <description of what should be done>. |
It's mandatory to use a related JIRA ticket number.
We try not using to use commented-out code. If there is no another option and code have to be commented then TODOs (with related JIRA ticket) have to be added before commented out code.
...
Configure IDEA to stripe trailing spaces and add a blank line to the end of the file.
We try to not use commented code. So, in case if test(s) is broken the test should be annotated @Ignore
with a related to JIRA ticket comment which describe a describes reason of failfailure.
If the test hangs or works too long then
Code Block |
---|
@Ignore("https://issues.apache.org/jira/browse/IGNITE-10178") |
Annotation The annotation should be added in the line preceding respective @Test
annotation.
...
Additionally, it is recommended to use Assume API (org.junit.Assume)
if you want to conditionally skip some testtests.
Code Block |
---|
Assume.assumeFalse("https://issues.apache.org/jira/browse/IGNITE-10178", conditionToSkip()); |
...
Apache Ignite has settings of inspection rules that are recommended to use during Ignite development. Settings can be found at <project directory>\.idea\inspectionProfiles\Project_Default.xml and will be automatically set as project default settings at first checkout.
...