docs/bugpattern/BadInstanceof.md

Flags `instanceof` checks where the expression can be determined to be a
supertype of the type it is compared to.

[JLS 15.28](https://docs.oracle.com/javase/specs/jls/se8/html/jls-15.html#jls-15.28)
specifically calls `instanceof` out as *not* being a compile-time constant
expression, so the usage of this pattern can lead to unreachable code that won't
be flagged by the compiler:

```java
class Foo {
  void doSomething() {
    if (this instanceof Foo) { // BAD: always true
      return;
    }
    interestingProcessing();
  }
}
```

In general, an `instanceof` comparison against a superclass is equivalent to a
null check:

```java
foo instanceof Foo
```

```java
foo != null
```

Pattern-matching `instanceof`s introduce some extra complexity into this. It may
be tempting to use an `instanceof` check to define a narrowly-scoped local
variable which gets reused within an expression, for example,

```java
return proto.getSubMessage() instanceof SubMessage sm
    && sm.getForename().equals("John")
    && sm.getSurname().equals("Smith");
```

We feel this urge should be resisted. While this is a clever trick to avoid an
extra line, it is not a true `instanceof` check, and declaring a variable
normally is clearer:

```java
SubMessage sm = proto.getSubMessage();
return sm.getForename().equals("John") && sm.getSurname().equals("Smith");
```