View source for Manual:Coding conventions/Java

<languages/>
{{Development guideline}}
<translate><!--T:1--> This page describes the '''coding conventions''' used within files of the [[<tvar name=man>Special:MyLanguage/Manual:Code</tvar>|MediaWiki codebase]] written in '''Java'''.</translate>
<translate><!--T:2--> See also the [[<tvar name=man>Special:MyLanguage/Manual:Coding conventions#All languages</tvar>|general conventions]] that apply to all program languages, including Java.</translate>

<translate>
== Build == <!--T:11-->
</translate>
<translate><!--T:12--> Maven is used as a build tool.</translate>
<translate><!--T:34--> All projects should inherit from the [[<tvar name="1">gitlab:repos/ci-tools/wmf-jvm-parent-pom</tvar>|JVM Parent POM]].</translate>
<translate><!--T:13--> It configures a number of static analysis tools and linters that will help in keeping projects coherent.</translate>
<translate><!--T:39--> Code conventions are embodied in the  [[<tvar name="1">gitlab:repos/ci-tools/wmf-maven-tool-configs/-/blob/main/src/main/resources/org/wikimedia/build/tools/checkstyle/checkstyle.xml</tvar>|configuration]] used by that pom.xml and will not be repeated here.</translate>
<translate><!--T:40--> The [[<tvar name="1">gitlab:repos/ci-tools/wmf-jvm-parent-pom/-/blob/main/README.md</tvar>|README]] file in that project describes how to use this parent pom.</translate>

<translate><!--T:41--> Java projects hosted on Gerrit should be built by Jenkins by using the [[<tvar name="1">gerrit:plugins/gitiles/integration/config/+/refs/heads/master/jjb/job-templates.yaml#87</tvar>|-maven-java8-docker template]].</translate>
<translate><!--T:14--> Other templates are available to publish documentation and to manage the release process.</translate>

<translate>
<!--T:42-->
Java projects should be analyzed by [<tvar name="url">https://sonarcloud.io/organizations/wmftest</tvar> SonarCloud].

== Java version == <!--T:15-->
</translate>
<translate><!--T:16--> Most of our projects are at the moment targeting Java 8.</translate>
<translate><!--T:17--> We are in the process of transitioning to Java 11.</translate>

<translate>
<!--T:35-->
[<tvar name="url">https://sdkman.io/</tvar> SDKMAN] can help you manage multiple JDK and easily switch between them.

== Libraries == <!--T:18-->
</translate>
<translate><!--T:19--> A number of libraries are commonly used throughout our various Java projects.</translate>
<translate><!--T:20--> Using the same libraries for similar use cases can help coherence across projects.</translate>
<translate><!--T:21--> That being said, use the list below as suggestions, not as a hard rule.</translate>

<translate>
=== Production Code === <!--T:22-->

==== Guava ==== <!--T:23-->
</translate>
<translate><!--T:24--> Guava is used on a number of projects.</translate>
<translate><!--T:25--> Note that in some cases, we have dependencies that themselves rely on outdated Guava versions, which prevents us from using the latest version.The features of Guava that we use the most are:</translate>

* [https://github.com/google/guava/wiki/PreconditionsExplained <translate><!--T:36--> Preconditions</translate>]
* [https://github.com/google/guava/wiki/ImmutableCollectionsExplained Immutable Collections]
* [https://github.com/google/guava/wiki/CachesExplained Caches] {{deprecated-inline}}

Note that [https://github.com/ben-manes/caffeine Caffeine] should be preferred to Guava for caching.

<translate>
==== Lombok ==== <!--T:26-->
</translate>
<translate><!--T:37--> While [<tvar name="url">https://projectlombok.org/features/all</tvar> Lombok] is not strictly a library, it provides very useful syntactic sugar to Java.</translate>
<translate><!--T:27--> Since Lombok is an annotation processor executed at compile time, Lombok has no runtime dependencies and is thus not creating compatibility issues.</translate>

<translate><!--T:38--> Lombok can be further configured by adding a <tvar name="1"><code>lombok.config</code></tvar> file at the package level, which might be particularly useful to make it play nice with Jackson.</translate>
<translate><!--T:28--> An example of such configuration:</translate>

 lombok.equalsAndHashCode.callSuper = call
 # disable SpotBugs, it does not like generated code by lombok
 lombok.extern.findbugs.addSuppressFBWarnings = true
 lombok.addLombokGeneratedAnnotation = true
 # useful for jackson that will be able to use the all args constructor when deserializing
 lombok.anyConstructor.addConstructorProperties = true

<translate>
<!--T:29-->
A few particularly useful features:
</translate>

* [https://projectlombok.org/features/Data @Data]: <translate><!--T:43--> makes it easy to generate DTO / DO, taking care of all this getters / setters and having a proper, valid <tvar name="1"><code>equals()</code></tvar> and <tvar name="2"><code>hashCode()</code></tvar>.</translate>
* [https://projectlombok.org/features/SneakyThrows @SneakyThrows]: <translate><!--T:44--> a better way of dealing with checked exceptions than wrapping them in an unchecked exception.</translate>

<translate><!--T:45--> Depending on your IDE, you might need to install a lombok plugin.</translate>
<translate><!--T:46--> See [<tvar name="url">https://www.projectlombok.org/setup/overview</tvar> documentation for your specific IDE].</translate>

<translate>
==== JSR 305 ==== <!--T:30-->
</translate>
<translate><!--T:31--> JSR 305 provides annotations to better document expected behaviour and help detect bugs.</translate>
<translate><!--T:32--> Those annotations are only compile time dependencies and not required at runtime, they don't generate dependency issues.</translate>

<translate>
<!--T:33-->
In particular:
</translate>

* [http://checkstyle-addons.github.io/jsr305-javadoc/3.0.1/javax/annotation/Nonnull.html @Nonnull] / [http://checkstyle-addons.github.io/jsr305-javadoc/3.0.1/javax/annotation/Nullable.html @Nullable] - <translate><!--T:47--> specifies that a method parameter or return value should be non-null or nullable.</translate>
* [http://checkstyle-addons.github.io/jsr305-javadoc/3.0.1/javax/annotation/ParametersAreNonnullByDefault.html @ParametersAreNonnullByDefault] - <translate><!--T:48--> all parameters on this class / package / method are expected to be non null unless otherwise specified.</translate>
* [http://checkstyle-addons.github.io/jsr305-javadoc/3.0.1/javax/annotation/concurrent/Immutable.html @Immutable]: this class is immutable.
* [http://checkstyle-addons.github.io/jsr305-javadoc/3.0.1/javax/annotation/concurrent/ThreadSafe.html @ThreadSafe] / [http://checkstyle-addons.github.io/jsr305-javadoc/3.0.1/javax/annotation/concurrent/NotThreadSafe.html @NotThreadSafe]: <translate><!--T:49--> this class is or is not thread safe.</translate>

==== JSON / XML ====

<translate><!--T:50--> [<tvar name="url">https://github.com/FasterXML/jackson</tvar> Jackson] is used for most JSON and XML parsing / serialization, with the use of [<tvar name="url2">https://github.com/FasterXML/jackson-annotations</tvar> annotations].</translate>

<translate>
==== HTTP client ==== <!--T:51-->

<!--T:52-->
[<tvar name="url">https://hc.apache.org/</tvar> Apache HttpComponents] is used as an HTTP client.
</translate>

<translate><!--T:53--> As much as possible a single instance of <tvar name="1"><code>HttpClient</code></tvar> should be shared within an application.</translate>
<translate><!--T:54--> A custom <tvar name=1>User-Agent</tvar> string should be configured.</translate>

<translate>
=== Testing === <!--T:55-->

==== Unit Testing Framework ==== <!--T:56-->
</translate>
<translate><!--T:57--> We mostly use [<tvar name="url">https://junit.org/</tvar> JUnit] as a testing framework.</translate>
<translate><!--T:58--> Some projects are using [<tvar name="url">https://junit.org/junit4/</tvar> JUnit 4], while others are using JUnit 5.</translate>
<translate><!--T:59--> Some projects have dependencies on component specific testing libraries that don't support [<tvar name="url">https://junit.org/junit5/</tvar> JUnit 5] yet.</translate>
<translate><!--T:60--> For projects that don't have this limitation, JUnit 5 should be preferred.</translate>

<translate>
==== Mocking ==== <!--T:61-->

<!--T:62-->
[<tvar name="url">https://site.mockito.org/</tvar> Mockito] is used as a mocking framework where needed.

==== HTTP Mocking ==== <!--T:63-->
</translate>
<translate><!--T:64--> [<tvar name="url">https://wiremock.org/docs/</tvar> WireMock] is used as an HTTP mock server, which allows testing code that relies on HTTP interactions.</translate>
<translate><!--T:65--> Note that WireMock makes it easy to also test various faults (delays, timeout, etc...).</translate>

<translate>
==== Assertions ==== <!--T:66-->
</translate>
<translate><!--T:67--> [<tvar name="url">https://assertj.github.io/doc/</tvar> AssertJ] is our main assertion framework.</translate>
<translate><!--T:68--> In almost all cases AssertJ should be preferred over plain <tvar name="1"><code>assert</code></tvar>, JUnit assertions or Hamcrest.</translate>

<translate>
== Various conventions == <!--T:69-->

=== Unit vs Integration Tests === <!--T:70-->

<!--T:71-->
We follow the usual naming conventions to identify [<tvar name="url">https://maven.apache.org/surefire/maven-surefire-plugin/examples/inclusion-exclusion.html</tvar> unit tests] vs [<tvar name="url2">https://maven.apache.org/surefire/maven-failsafe-plugin/examples/inclusion-exclusion.html</tvar> integration tests].

=== Managing <tvar name="1"><code>null</code></tvar> and defensive programming === <!--T:72-->
</translate>
<translate><!--T:73--> As much as possible, <tvar name=1><code>null</code></tvar> values should be avoided.</translate>
[[w:Null object pattern|Null Objects]] should be preferred.
<translate><!--T:74--> Parameters should be expected to be non null and not explicitly checked, unless they come from an untrusted caller.</translate>
<translate><!--T:75--> Parameters should be marked with <tvar name="1"><code>@Nonnull</code></tvar> / <tvar name="2"><code>@Nullable</code></tvar> to allow static analysis tools to validate nullity.</translate>

Optionals should be used sparingly. Read [https://blogs.oracle.com/javamagazine/post/optional-class-null-pointer-drawbacks this blog post] before committing to using Optionals.

=== serialVersionUID ===

<translate>
==== Context ==== <!--T:76-->
</translate>
<translate><!--T:77--> [<tvar name="url">https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/Serializable.html</tvar> Serialization] and the use of serialVersionUID is [<tvar name="url2">https://github.com/projectlombok/lombok/wiki/WHY-NOT:-serialVersionUID</tvar> complex topic].</translate>
<translate><!--T:78--> In short:</translate>

* <translate><!--T:79--> when a class is serialized, it's <tvar name="1"><code>serialVersionUID</code></tvar> is part of the serialization</translate>
* <translate><!--T:80--> when a class is deserialized, the serialized <tvar name="1"><code>serialVersionUID</code></tvar> is compared with the target class, if they don't match, deserialization fails</translate>
* <translate><!--T:81--> <tvar name="1"><code>serialVersionUID</code></tvar> can be set manually, otherwise it is auto computed by the serialization runtime, the UID will change if the structure of the class changes, it might be different across different JRE vendors or versions</translate>

<translate>
<!--T:82-->
Leaving the runtime to compute the <tvar name="1"><code>serialVersionUID</code></tvar> can lead to cases where class versions should be compatible but still fail deserialization.

<!--T:83-->
Manually setting the <tvar name=1><code>serialVersionUID</code></tvar> can lead to cases where class versions should '''not''' be compatible but still successfully deserialize, leading to silent problems (when the class structure has changed, but the <tvar name=1><code>serialVersionUID</code></tvar> has not been updated).

==== guidelines ==== <!--T:84-->

<!--T:85-->
<tvar name="1"><code>serialVersionUID</code></tvar> should be manually defined only when:
</translate>

* <translate><!--T:86--> classes are expected to be deserialized (not if they ''just'' need to extend Serializable)</translate>
* <translate><!--T:87--> the class or JVM version might change between serialization and deserialization</translate>

<translate><!--T:88--> If manually defined, <tvar name="1"><code>serialVersionUID</code></tvar> should start at <tvar name="2"><code>0</code></tvar> and be incremented on each change to the class structure.</translate> 
<translate><!--T:89--> The range from <tvar name="1"><code>0</code></tvar> to <tvar name="2"><code>10000</code></tvar> is considered non-generated by the FindBugs' <tvar name=3>[https://github.com/mebigfatguy/fb-contrib/blob/spotbugs/src/main/java/com/mebigfatguy/fbcontrib/detect/ImmatureClass.java#L44 <code>ImmatureClass</code>]</tvar> rules</translate>

=== Constants ===

Constants are declared following the usual Java convention: <code>public static final <TYPE> CONSTANT_NAME</code> with the constant name in capital letters.

Scala constants follow the [https://docs.scala-lang.org/style/naming-conventions.html#constants-values-and-variables usual convention] of using UpperCamelCase.

== Maven ==

=== Dependencies ===
In multi module projects, we define version numbers in the main pom of the project, in the <code>[https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management <dependencyManagement/>]</code> section. This ensures that if a dependency is used in multiple modules, the same version of that dependency is used. Even if a dependency is used in a single module, we still define version in the main pom of the project. In the rare case where a module needs a different version of a dependency than the rest of the project, it is defined in the pom of that module. This makes it easier to spot exceptions.

When multiple dependencies share the same version, that version number is specified as a property. For example, we often use Jackson, which provides multiple jars for different extensions, all those jars needs to share the same version number.

{{Conventions navigation}}