sortedFoos = new ArrayList<>(foos);
22 | Collections.sort(sortedFoos);
23 | return sortedFoos;
24 | }
25 | ```
26 |
--------------------------------------------------------------------------------
/docs/bugpattern/UnusedMethod.md:
--------------------------------------------------------------------------------
1 | The presence of an unused method may indicate a bug. This check highlights
2 | _private_ methods which are unused and can be safely removed without considering
3 | the impact on other source files.
4 |
5 | ## Suppression
6 |
7 | Methods and fields which are used by reflection can be annotated with `@Keep` to
8 | suppress the warning.
9 |
10 | This annotation can also be applied to annotations, to suppress the warning for
11 | any member annotated with that annotation:
12 |
13 | ```java
14 | import com.google.errorprone.annotations.Keep;
15 |
16 | @Keep
17 | @Retention(RetentionPolicy.RUNTIME)
18 | @interface Field {}
19 |
20 | ...
21 |
22 | public class Data {
23 | @Field private int a; // no warning.
24 | ...
25 | }
26 | ```
27 |
28 | All false positives can be suppressed by annotating the method with
29 | `@SuppressWarnings("unused")` or prefixing its name with `unused`.
30 |
--------------------------------------------------------------------------------
/docs/bugpattern/UseBinds.md:
--------------------------------------------------------------------------------
1 | A @Provides or @Produces method that returns its single parameter has long been
2 | Dagger's only mechanism for delegating a binding. Since the delegation is
3 | implemented via a user-defined method there is a disproportionate amount of
4 | overhead for such a conceptually simple operation. @Binds was introduced to
5 | provide a declarative way of delegating from one binding to another in a way
6 | that allows for minimal overhead in the implementation. @Binds should always be
7 | preferred over @Provides or @Produces for delegation.
8 |
9 | For instance, the following `@Provides` method
10 |
11 | ```java
12 | @Provides static Heater provideHeater(ElectricHeater heater) {
13 | return heater;
14 | }
15 | ```
16 |
17 | is equivalent to the following preferred `@Binds` method.
18 |
19 | ```java
20 | @Binds abstract Heater bindHeater(ElectricHeater impl);
21 | ```
22 |
--------------------------------------------------------------------------------
/docs/bugpattern/VarTypeName.md:
--------------------------------------------------------------------------------
1 | As of JDK 10 `var` is a restricted local variable type and cannot be used for
2 | type declarations (see [JEP 286][]).
3 |
4 | [JEP 286]: https://openjdk.java.net/jeps/286
5 |
--------------------------------------------------------------------------------
/docs/bugpattern/VariableNameSameAsType.md:
--------------------------------------------------------------------------------
1 | When a field/variable name is the same as the field/variable type, it is
2 | difficult to determine which to use at which time.
3 |
4 | For example,
5 |
6 | ```java
7 | private static String String;
8 | ```
9 |
10 | This would cause future use of String.something within this class to refer to
11 | the static field String, instead of the class String.
12 |
13 | This is worth calling out to avoid confusion and is a violation of
14 | [Google Java style naming conventions](https://google.github.io/styleguide/javaguide.html#s5.2.7-local-variable-names)
15 |
16 | Instead of this naming style, the correct way would be:
17 |
18 | ```java
19 | private static String string;
20 | ```
21 |
--------------------------------------------------------------------------------
/docs/bugpattern/WithSignatureDiscouraged.md:
--------------------------------------------------------------------------------
1 | `withSignature` relies on the string representation of internal classes in the
2 | javac implementation. Those string representations are not necessarily stable
3 | across versions of javac, and they can change when a method is annotated with
4 | type-use annotations.
5 |
6 | Additionally, `withSignature` currently has at least one undocumented behavioral
7 | quirk.
8 |
9 | The most reasonable use case for `withSignature` is for methods that declare or
10 | use type variables, which are difficult or impossible to express with the rest
11 | of the `MethodMatchers` API. Still, where practical, prefer to write your own
12 | matching code instead of using `withSignature`.
13 |
--------------------------------------------------------------------------------
/docs/bugpattern/WrongOneof.md:
--------------------------------------------------------------------------------
1 | When switching over a proto `one_of`, getters that don't match the current case
2 | are guaranteed to be return a default instance:
3 |
4 | ```java
5 | switch (foo.getBlahCase()) {
6 | case FOO:
7 | return foo.getFoo();
8 | case BAR:
9 | return foo.getFoo(); // should be foo.getBar()
10 | }
11 | ```
12 |
--------------------------------------------------------------------------------
/docs/bugpattern/XorPower.md:
--------------------------------------------------------------------------------
1 | The `^` binary XOR operator is sometimes mistaken for a power operator, but e.g.
2 | `2 ^ 2` evaluates to `0`, not `4`.
3 |
4 | Consider expressing powers of `2` using a bit shift instead.
5 |
--------------------------------------------------------------------------------
/docs/bugpattern/android/BinderIdentityRestoredDangerously.md:
--------------------------------------------------------------------------------
1 | Binder is Android's inter-process communication mechanism. Each call to
2 | `Binder.clearCallingIdentity()` should be followed by
3 | `Binder.restoreCallingIdentity()` in a finally block. Otherwise the wrong Binder
4 | identity may be used by subsequent code.
5 |
6 | For example: `java long token = Binder.clearCallingIdentity(); // Issue a Binder
7 | call (may throw an Exception). someBinderInterface.makeCall();
8 | Binder.restoreCallingIdentity(token);`
9 |
10 | The above code should be rewritten as: `java long token =
11 | Binder.clearCallingIdentity(); try { // Issue a Binder call (may throw an
12 | Exception). someBinderInterface.makeCall(); } finally {
13 | Binder.restoreCallingIdentity(token); }`
14 |
--------------------------------------------------------------------------------
/docs/bugpattern/android/FragmentNotInstantiable.md:
--------------------------------------------------------------------------------
1 | Every subclass of `Fragment` must be public and have a public, nullary
2 | constructor. The Android framework will reflectively instantiate them after a
3 | configuration change, such as screen rotation, and if the class is not
4 | instantiable by `Class#newInstance()`, an `InstantiationException` will be
5 | thrown.
6 |
7 | In addition, it is strongly recommended that subclasses not have other
8 | constructors with parameters, since these constructors will not be called when
9 | the fragment is re-instantiated; instead, arguments should be supplied with
10 | `setArguments(Bundle)` and retrieved with `getArguments()`.
11 |
12 | For more information, please see the documentation for
13 | [Fragment](https://developer.android.com/reference/android/app/Fragment.html#Fragment\(\)).
14 |
15 | This check is an adaptation of the `ValidFragment` rule of
16 | [Android Lint](https://tools.android.com/tips/lint-checks).
17 |
--------------------------------------------------------------------------------
/docs/bugpattern/android/HardCodedSdCardPath.md:
--------------------------------------------------------------------------------
1 | Your code should not reference the `/sdcard` path directly, which is
2 | platform-dependent. You should use
3 | `Environment.getExternalStorageDirectory().getPath()` instead.
4 |
5 | Similarly, do not reference the `/data/data/` path directly, as it can vary in
6 | multi-user scenarios. You should use `Context.getFilesDir().getPath()` instead.
7 |
8 | For more information, please see the documentation for
9 | [android.os.Environment](https://developer.android.com/reference/android/os/Environment.html)
10 | and
11 | [android.content.Context](https://developer.android.com/reference/android/content/Context.html).
12 |
13 | This check is an adaptation of the `SdCardPath` rule of
14 | [Android Lint](https://tools.android.com/tips/lint-checks).
15 |
--------------------------------------------------------------------------------
/docs/bugpattern/flogger/FloggerLogWithCause.md:
--------------------------------------------------------------------------------
1 | When using a logger as error handling, setting the exception as the cause of the
2 | log statement will provide more context in the log message.
3 |
4 | Instead of:
5 |
6 | ```java
7 | try {
8 | ...
9 | } catch (Exception e) {
10 | logger.atWarning().log("Failed!");
11 | }
12 | ```
13 |
14 | Consider:
15 |
16 | ```java
17 | try {
18 | ...
19 | } catch (Exception e) {
20 | logger.atWarning().withCause(e).log("Failed!");
21 | }
22 | ```
23 |
--------------------------------------------------------------------------------
/docs/bugpattern/flogger/FloggerRedundantIsEnabled.md:
--------------------------------------------------------------------------------
1 | Guarding flogger log statements with an explicit log level check is redundant,
2 | since the log statement already contains the desired log level and is
3 | inexpensive to evaluate if the specified log level is disabled.
4 |
5 | This is redundant:
6 |
7 | ```java
8 | if (logger.atInfo().isEnabled()) {
9 | logger.atInfo().log(\"blah\");
10 | }
11 | ```
12 |
13 | If the log statement's *arguments* are expensive to evaluate, consider using
14 | lazy argument evaluation
15 | (https://google.github.io/flogger/examples#logging-with-lazy-argument-evaluation-java8):
16 |
17 | ```java
18 | logger.atFine().log(\"Value: %s\", lazy(() -> process(x, y)));
19 | ```
20 |
--------------------------------------------------------------------------------
/docs/bugpattern/flogger/FloggerWithoutCause.md:
--------------------------------------------------------------------------------
1 | Flogger uses `withCause(exception)` to associate Exceptions with log statements.
2 | Passing exceptions directly to `log()` only records the name and message,
3 | and loses the stack trace.
4 |
5 | ```java
6 | logger.atWarning().log("Unexpected exception: %s", e);
7 | ```
8 |
9 | ```java
10 | logger.atWarning().withCause(e).log("Unexpected exception");
11 | ```
12 |
13 | If you intended not to log the stack trace or other parts of the exception, you
14 | should explicitly log the parts you want to keep so the intent is clear in the
15 | code:
16 |
17 | ```java
18 | // Avoid withCause() since stack traces are unnecessary here
19 | logger.atWarning().log("Unexpected exception [%s]: %s", e.getClass(), e.getMessage());
20 | ```
21 |
--------------------------------------------------------------------------------
/docs/bugpattern/inject/InjectOnMemberAndConstructor.md:
--------------------------------------------------------------------------------
1 | When a class uses `@Inject` on a field, and that field is also assigned from an
2 | `@Inject` constructor, then the field is assigned twice from the DI Injector.
3 | This may result in 2 objects being created, where the first instance is assigned
4 | then thrown away after the second injection.
5 |
6 | A simple solution is to remove the `@Inject` annotation from the injected field.
7 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/AlmostJavadoc.md:
--------------------------------------------------------------------------------
1 | This comment contains Javadoc or HTML tags, and is in the right position for a
2 | Javadoc, but doesn't start with a double asterisk. Should it be a Javadoc?
3 |
4 | ```java
5 | /* Frobnicates the {@link Foo}s. */
6 | class Frobnicator {
7 | Foo frobnicate(Foo foo);
8 | }
9 | ```
10 |
11 | ```java
12 | /** Frobnicates the {@link Foo}s. */
13 | class Frobnicator {
14 | Foo frobnicate(Foo foo);
15 | }
16 | ```
17 |
18 | ## Suppression
19 |
20 | Suppress by applying `@SuppressWarnings("AlmostJavadoc")` to the element being
21 | documented (or not documented).
22 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/EscapedEntity.md:
--------------------------------------------------------------------------------
1 | HTML entities used within `@code` and `@literal` tags will be interpreted
2 | directly rather than converted to the expected characters. For example, this is
3 | wrong:
4 |
5 | ```java
6 | /**
7 | * {@code
8 | * @Override
9 | * public boolean equals(Object o) {
10 | * return false;
11 | * }
12 | * }
13 | */
14 | ```
15 |
16 | An option is to drop the {@code } tags, though this will then require escaping
17 | any generic type parameters which may otherwise be interpreted as HTML. That is,
18 | `List` is the text "List" followed by the (non-existent) tag "Integer".
19 |
20 | ```java
21 | /**
22 | *
23 | * @Override
24 | * public boolean equals(Object o) {
25 | * return false;
26 | * }
27 | *
28 | */
29 | ```
30 |
31 | ## Suppression
32 |
33 | Suppress by applying `@SuppressWarnings("EscapedEntity")` to the element being
34 | documented.
35 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/InheritDoc.md:
--------------------------------------------------------------------------------
1 | The `@inheritDoc` tag should only be used on classes/interfaces which extend or
2 | implement another and methods which override a method from a superclass.
3 |
4 | ```java
5 | class Frobnicator {
6 | /** {@inheritDoc} */
7 | public void frobnicate() {
8 | // ...
9 | }
10 | }
11 | ```
12 |
13 | ## Suppression
14 |
15 | Suppress by applying `@SuppressWarnings("InheritDoc")` to the element being
16 | documented.
17 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/InvalidParam.md:
--------------------------------------------------------------------------------
1 | Javadoc's `@param` tag should not be used to document parameters which do not
2 | appear in the formal parameter list. This may indicate a typo, or an omission
3 | when refactoring.
4 |
5 | ```java
6 | /**
7 | * Parses {@code input} as a proto.
8 | *
9 | * @param inputBytes input bytes to parse.
10 | */
11 | MyProto parse(byte[] input) {
12 | ...
13 | }
14 | ```
15 |
16 | ## Suppression
17 |
18 | Suppress by applying `@SuppressWarnings("InvalidParam")` to the element being
19 | documented.
20 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/InvalidThrows.md:
--------------------------------------------------------------------------------
1 | The `@throws` tag should not document a checked exception which is not actually
2 | thrown by the documented method.
3 |
4 | ```java
5 | /**
6 | * Validates {@code n}.
7 | *
8 | * @throws Exception if n is negative.
9 | */
10 | void validate(int n) {
11 | ...
12 | }
13 | ```
14 |
15 | ## Suppression
16 |
17 | Suppress by applying `@SuppressWarnings("InvalidThrows")` to the element being
18 | documented.
19 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/InvalidThrowsLink.md:
--------------------------------------------------------------------------------
1 | `@throws` does not require `@link`ing the target exception.
2 |
3 | ```java
4 | /**
5 | * Validates {@code n}.
6 | *
7 | * @throws {@link Exception} if n is negative.
8 | */
9 | void validate(int n) throws Exception {
10 | ...
11 | }
12 | ```
13 |
14 | ```java
15 | /**
16 | * Validates {@code n}.
17 | *
18 | * @throws Exception if n is negative.
19 | */
20 | void validate(int n) throws Exception {
21 | ...
22 | }
23 | ```
24 |
25 | ## Suppression
26 |
27 | Suppress by applying `@SuppressWarnings("InvalidThrowsLink")` to the element
28 | being documented.
29 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/MalformedInlineTag.md:
--------------------------------------------------------------------------------
1 | This error is triggered by a malformed inline tag, anywhere @{tag appears
2 | instead of {@tag inside a Javadoc comment. See [javadoc documentation][javadoc]
3 | for more explanation on the use of inline tags.
4 |
5 | [javadoc]: https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDJGIJB
6 |
7 | ## Suppression
8 |
9 | Suppress by applying `@SuppressWarnings("MalformedInlineTag")` to the element
10 | being documented.
11 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/MissingSummary.md:
--------------------------------------------------------------------------------
1 | Javadocs on private and protected elements are required to contain a short
2 | summary line. This is often the only part of the Javadoc that others will see
3 | surfaced in various tools.
4 |
5 | ```java
6 | /** @return deserialised proto */
7 | public Proto parse(byte[] bytes) {
8 | ...
9 | }
10 | ```
11 |
12 | ```java
13 | /** Returns deserialised proto. */
14 | public Proto parse(byte[] bytes) {
15 | ...
16 | }
17 | ```
18 |
19 | ## Suppression
20 |
21 | Suppress by applying `@SuppressWarnings("MissingSummary")` to the element being
22 | documented.
23 |
--------------------------------------------------------------------------------
/docs/bugpattern/javadoc/ReturnFromVoid.md:
--------------------------------------------------------------------------------
1 | Methods which do not return anything should not have a `@return` tag.
2 |
3 | ```java
4 | /**
5 | * Frobnicates.
6 | *
7 | * @return a frobnicator
8 | */
9 | void frobnicator(int a) {
10 | ...
11 | }
12 | ```
13 |
14 | ## Suppression
15 |
16 | Suppress by applying `@SuppressWarnings("ReturnFromVoid")` to the element being
17 | documented.
18 |
--------------------------------------------------------------------------------
/docs/bugpattern/time/StronglyTypeTime.md:
--------------------------------------------------------------------------------
1 | Where possible, `java.time.Duration` fields should be strongly typed rather than
2 | stored as integral primitives and converted at the usage site.
3 |
4 | For example, rather than:
5 |
6 | ```java
7 | public class X {
8 | private static final long TIMEOUT = 100;
9 |
10 | // later in the file
11 | use(Duration.ofMillis(TIMEOUT));
12 | }
13 | ```
14 |
15 | Prefer:
16 |
17 | ```java
18 | public class X {
19 | private static final Duration TIMEOUT = Duration.ofMillis(100);
20 |
21 | // later in the file
22 | use(TIMEOUT);
23 | }
24 | ```
25 |
--------------------------------------------------------------------------------
/examples/plugin/bazel/java/com/google/errorprone/sample/BUILD:
--------------------------------------------------------------------------------
1 | java_plugin(
2 | name = "MyCustomCheckPlugin",
3 | srcs = ["MyCustomCheck.java"],
4 | deps = [
5 | "@error_prone//jar",
6 | "@guava//jar",
7 | "//third_party/java/auto_service",
8 | ],
9 | )
10 |
11 | java_library(
12 | name = "Hello",
13 | srcs = ["Hello.java"],
14 | plugins = [":MyCustomCheckPlugin"],
15 | )
16 |
--------------------------------------------------------------------------------
/examples/plugin/bazel/third_party/java/auto_service/BUILD:
--------------------------------------------------------------------------------
1 | licenses(["notice"]) # Apache License 2.0
2 |
3 | java_library(
4 | name = "auto_service",
5 | exported_plugins = [":auto_service_plugin"],
6 | visibility = ["//visibility:public"],
7 | exports = ["@auto_service//jar"],
8 | runtime_deps = ["@guava//jar"],
9 | )
10 |
11 | java_plugin(
12 | name = "auto_service_plugin",
13 | processor_class = "com.google.auto.service.processor.AutoServiceProcessor",
14 | deps = [
15 | "@auto_common//jar",
16 | "@auto_service//jar",
17 | "@guava//jar",
18 | ],
19 | )
20 |
--------------------------------------------------------------------------------