README.md

Error Prone Support

Error Prone Support is a Picnic-opinionated extension of Google's Error Prone. It aims to improve code quality, focussing on maintainability, consistency and avoidance of common pitfalls.

Error Prone is a static analysis tool for Java that catches common programming mistakes at compile-time.

Read more on how Picnic uses Error Prone (Support) in the blog post Picnic loves Error Prone: producing high-quality and consistent Java code.

Getting started • Developing Error Prone Support • How it works • Contributing

---

⚡ Getting started

Installation

This library is built on top of Error Prone. To use it:

1. First, follow Error Prone's installation guide.

2. Next, edit your pom.xml file to add one or more Error Prone Support modules to the annotationProcessorPaths of the maven-compiler-plugin:

   <build>
       <pluginManagement>
           <plugins>
               <plugin>
                   <groupId>org.apache.maven.plugins</groupId>
                   <artifactId>maven-compiler-plugin</artifactId>
                   <configuration>
                       <annotationProcessorPaths>
                           <!-- Error Prone itself. -->
                           <path>
                               <groupId>com.google.errorprone</groupId>
                               <artifactId>error_prone_core</artifactId>
                               <version>${error-prone.version}</version>
                           </path>
                           <!-- Error Prone Support's additional bug checkers. -->
                           <path>
                               <groupId>tech.picnic.error-prone-support</groupId>
                               <artifactId>error-prone-contrib</artifactId>
                               <version>${error-prone-support.version}</version>
                           </path>
                           <!-- Error Prone Support's Refaster rules. -->
                           <path>
                               <groupId>tech.picnic.error-prone-support</groupId>
                               <artifactId>refaster-runner</artifactId>
                               <version>${error-prone-support.version}</version>
                           </path>
                       </annotationProcessorPaths>
                       <compilerArgs>
                           <arg>
                               -Xplugin:ErrorProne
                               <!-- Add other Error Prone flags here. See
                               https://errorprone.info/docs/flags. -->
                           </arg>
                           <arg>-XDcompilePolicy=simple</arg>
                       </compilerArgs>
                       <!-- Some checks raise warnings rather than errors. -->
                       <showWarnings>true</showWarnings>
                       <!-- Enable this if you'd like to fail your build upon warnings. -->
                       <!-- <failOnWarning>true</failOnWarning> -->
                   </configuration>
               </plugin>
           </plugins>
       </pluginManagement>
   </build>

Seeing it in action

Consider the following example code:

import com.google.common.collect.ImmutableSet;
import java.math.BigDecimal;

public class Example {
  static BigDecimal getNumber() {
    return BigDecimal.valueOf(0);
  }

  public ImmutableSet<Integer> getSet() {
    ImmutableSet<Integer> set = ImmutableSet.of(1);
    return ImmutableSet.copyOf(set);
  }
}

If the installation was successful, then building the above code with Maven should yield two compiler warnings:

$ mvn clean install
...
[INFO] Example.java:[9,34] [Refaster Rule] BigDecimalRules.BigDecimalZero: Refactoring opportunity
    (see https://error-prone.picnic.tech/refasterrules/BigDecimalRules#BigDecimalZero)
  Did you mean 'return BigDecimal.ZERO;'?
...
[WARNING] Example.java:[13,35] [IdentityConversion] This method invocation appears redundant; remove it or suppress this warning and add a comment explaining its purpose
    (see https://error-prone.picnic.tech/bugpatterns/IdentityConversion)
  Did you mean 'return set;' or '@SuppressWarnings("IdentityConversion") public ImmutableSet<Integer> getSet() {'?
...

Two things are kicking in here:

1. An Error Prone BugChecker that flags unnecessary identity conversions.
2. A Refaster rule capable of rewriting expressions of the form BigDecimal.valueOf(0) and new BigDecimal(0) to BigDecimal.ZERO.

Be sure to check out all bug checks and refaster rules.

👷 Developing Error Prone Support

This is a Maven project, so running mvn clean install performs a full clean build and installs the library to your local Maven repository. Some relevant flags:

• -Dverification.warn makes the warnings and errors emitted by various plugins and the Java compiler non-fatal, where possible.
• -Dverification.skip disables various non-essential plugins and compiles the code with minimal checks (i.e. without linting, Error Prone checks, etc.).
• -Dversion.error-prone=some-version runs the build using the specified version of Error Prone. This is useful e.g. when testing a locally built Error Prone SNAPSHOT.
• -Perror-prone-fork runs the build using Picnic's Error Prone fork, hosted on Jitpack. This fork generally contains a few changes on top of the latest Error Prone release.
• -Pself-check runs the checks defined by this project against itself. Pending a release of google/error-prone#3301, this flag must currently be used in combination with -Perror-prone-fork.

Some other commands one may find relevant:

• mvn fmt:format formats the code using google-java-format.
• ./run-mutation-tests.sh runs mutation tests using Pitest. The results can be reviewed by opening the respective target/pit-reports/index.html files. For more information check the PIT Maven plugin.
• ./apply-error-prone-suggestions.sh applies Error Prone and Error Prone Support code suggestions to this project. Before running this command, make sure to have installed the project (mvn clean install) and make sure that the current working directory does not contain unstaged or uncommited changes.

When running the project's tests in IntelliJ IDEA, you might see the following error:

java: exporting a package from system module jdk.compiler is not allowed with --release

If this happens, go to Settings -> Build, Execution, Deployment -> Compiler -> Java Compiler and deselect the option Use '--release' option for cross-compilation (Java 9 and later). See IDEA-288052 for details.

💡 How it works

This project provides additional BugChecker implementations.

✍️ Contributing

Want to report or fix a bug, suggest or add a new feature, or improve the documentation? That's awesome! Please read our contribution guidelines.