A working Intelji IDEA development environment can be obtained by ./gradlew idea
and then importing the generated project (owl.ipr
) to IDEA.
If you instead want to work with the IDEA Gradle plugin, import the project as usual ("Open Project" > build.gradle
) and perform the following configuration:
config/idea-codestyle.xml
config/idea-inspection-profile.xml
config/dictionary.dic
Before submitting code please executed ./gradlew check
locally to run all code checks. Apart from jUnit tests, static code analysis is performed using PMD and ErrorProne (rules are located in the config
folder). Further, checkstyle is used to check compliance with the Google Java Style Guide. Passing all these tests is mandatory for submitted code.
In general, features of Java 11, like Lambdas, Streams, Collections.of
, forEach
-style, etc., can and should be used frequently. Streams should only be used for prototypes or in non-performance critical code, since they do add noticeable overhead. Typical "best practises" like KISS and DRY should be adhered to, some performance can be sacrificed for clear and concise code. Nevertheless, performance must not be neglected.
assert
and Guavas Precondition
methods frequently, it drastically simplifies debugging and even can help reading code. Usually, asserts should only be used for internal consistency checks, i.e. double-checking your own implementation. For owl, assert
can also be used to check arguments if the check is extremely costly or in a very critical code section.The following conventions should be followed:
UnsupportedOperationException
: The operation is not supported yet, but this could change in the future.IllegalArgumentException
: This operation will never be supported (for the given input).Where applicable, JDK functionality should be preferred (e.g., JDK List.of
over Guava ImmutableList.of
). If the JDK does not offer some particular functionality, Guava usually provides it and that should be used. Before implementing your own methods, double check that none of owl's utility libraries provide it already.
Collections3
for some specific collection methods.fastutil
.naturals-util
for more specific implementations (e.g., index maps).For classes which are nothing more than immutable structs, i.e. data containers / tuples, Immutables should be used. See @Tuple
/ @HashedTuple
and their usages for examples. Hiding the implementation class (by, e.g., giving it package visibility) is recommended, since Java may support value types natively in the near future. Finally, for performance critical code, double-check that the generated code is doing what you expect from it (e.g., no superfluous copies are performed).
In general, everything should have self-explanatory, english names. Also, the following naming schemes should be followed:
Members of a class can be sorted alphabetically (adhering to the general order), but a logical structure is preferred. For example, one can keep setters and getter together or group methods by their type (e.g., simple property accessor, complex mutation, ...). For tuples (see above), the convention is the following: "fields", derived fields, factory methods ("of
"), constructor-like methods ("with...
"), other methods.
Javadoc isn't required everywhere, but strongly encouraged. Code without any documentation is not accepted. The Oracle and Google style guides apply. Specifically, block tags (like @throws
, @return
, etc.) should be continued by a lower-case sentence. For example, @throws IllegalArgumentException if the argument is not allowed
or @return the thing
.