jspecify faq - jspecify/jspecify GitHub Wiki

Read the Start Here page first.

Is now the time to adopt?

Not necessarily, but maybe. Read our page on adoption.

Why are you creating Yet Another jar of static analysis annotations?

This is the first one being created by a community consensus of tool and library owners. (JSR 305 was an attempt that was abandoned before completion.)

For the first time, a group of tool and library owners are doing the hard work to agree on a precisely defined set of semantics for Java nullness annotations, explained in our javadoc. Many of the existing JARs are owned by members of our group, who will be glad to (at least soft-)deprecate them.

This effort is also a key step on the journey toward an eventual Java language feature for declarative use-site nullness.

Doesn't Checker Framework already have the most thorough solution?

Checker Framework is an amazing tool. You should check it out.

Its design goal is to provide sound analysis: the nullness checker will guarantee that no NullPointerException can "possibly" happen at runtime, as long as its rules are followed. The cost of such a splendid guarantee is paid in some combination of (a) complexity, (b) migration difficulty, and (c) false positive rate; trade-offs that many users find well-worth accepting!

We're trying to create common semantics that can be shared by all tools, all libraries, all applications, all developers -- which Checker Framework can then extend. It would be hard for all of these and all of us to converge on the aggressive CF approach. We believe that most (not all!) users would rather use a tool that risks some false negatives in order to provide a smoother experience.

The EISOP Framework is a fork of the Checker Framework to support both JSpecify semantics and (by adding additional CF-specific annotations to your code) the full Checker Framework feature set as well. JSpecify's goal is to make sure these two layers can work together in harmony.

Why do you think your annotations are better in general?

We think that your code should not have to depend on tool-specific annotations. Also, you'll encounter many fine-grained questions over whether to annotate your code this way or that, and we're providing authoritative answers for those questions, many of them directly in the Javadoc.

OpenJDK is a member of our group, and if Java ever one day has null-aware types, the JSpecify standard will be the only reasonable starting point to base it on.

Still, all that will happen is that yours goes onto the long list of packages each tool recognizes.

Sure, for now. We're looking at the long arc. Our annotations will be the only tool-neutral, library-neutral, everything-neutral set that's been released. And we're putting a lot of work into them and their documentation. We don't think it will be long before most code prefers to depend on our annotations -- which can't do them much harm, since at worst they'll just be on every tool's list (just as the question implies).

Your tool might not be running our conformance tests yet, let alone passing them. But owners of several high-profile nullness analysis tools have been involved in JSpecify all along,and are working on getting there. (If that doesn't include your tool, we'd really love to hear from you.)

As more code starts using our annotations, at least that creates some incentives that point in the right direction. For example, a library user will file an issue to a library about how some API in that library is annotated. When in doubt, they and the library owner can refer to the JSpecify documentation (including the javadoc immediately on the annotation in question) to settle what to do. If either party says "but that makes my tool do something bad", then in some cases they'll take the logical step of filing a bug against that tool. The recipient of that bug would might sooner or later recognize that they have more interest in adhering to a standard than in regularly fighting this fight. If they don't like what they're having to do they will file bugs at us. Etc.

None of this is proof that everything will go quickly and smoothly! But there will be a natural path toward getting there, that doesn't seem counter to anyone's innate interest. Sounds like a good start.

Why is Google driving this effort?

Hello. Google here.

The short answer is that we became aware of the value of solving this problem, and were able and willing to invest in it.

We use static analysis very aggressively in our internal projects. We also have NullPointerExceptions very aggressively in our internal projects. This seems unfortunate, so we began hatching a scheme to roll out nullness analysis to our entire codebase. But that means we would need lots tools to all agree on the same semantics.

Plus, we have an extremely interdependent codebase, with individual pieces of that puzzle increasingly adopting Kotlin. This means a lot of calls back and forth across that gap, with nullness information being lost in both directions.

We've been leading the project, but we serve at the pleasure of the other members. So far we have had their confidence!

Why do your annotations all have runtime retention?

They can be useful for some runtime use cases, and we have no interest in preventing that.

We're aware that some toolchains have trouble of various kinds with runtime-retention annotations. But we don't think it makes sense to completely remove support for other use cases in response. If the tools in question can't be improved, then perhaps a new tool could alter our jar to downgrade the retention, or alter jars built against it to strip the out.

At the very worst, we would provide a second artifact with class-retention equivalents in a package like org.jspecify.annotations.classretention. We don't expect to need to do this, but it's an option.

Is all this just about null?

We would like to go further; we just picked the hardest thing to do first. (Note: not recommended.) We have jotted some notes in long term roadmap but have been quite focused on what's in front of us.

Why isn't Xyz a member?

We're open to it. Please ask us by email; we might need to reach out to them, or reach out again.

I have more questions about the nullness features

They might be answered in the nullness Design FAQ.