Null-Safe Compliance

Even within a single project it is not usually practical to enforce a rule like "We must have absolutely no NPE's." We therefore need to define various levels of "Null-Safe Compliance." Developers should be able to "switch" the level of compliance they want in the build system or right in the source code. Perhaps key modules or classes can be checked strictly while other classes are barely checked at all. Over time you can increase your compliance.

There are different levels of "compliance" to a "no NullPointerException guarantee." Each level is stricter but not necessarily "better." A lot of code would never need more than Level 3 to be considered very clean.

Level 1: checking aggregious errors, tool installed

Check for NPE's that necessarily occur, no matter what. A simple example would be:

String s = null;
return s.length();

Of course these types of bugs are rare. Becoming compliant at this level just means you have NullSafe installed as part of your development/build environment and it is operating at the simplest level.

Your classes are annotated such that they instruct NullSafe to skip all analysis except this most egregious of error.

Level 2: checking some classes with annotation

Selected classes are marked as "check me" instead of "skip me." Typically these classes are in core modules, are simple, or are brand new classes (it's easier to achieve compliance when starting fresh).

As each class becomes available for checking, the developers use any number of techniques to fix the possible NPE's — fix the logic outright, use JavaDoc annotations to document expected behavior, or use in-code annotations to cause the analysis engine to ignore those NPE's.

These checked classes then have this attribute: Either no NPE's are possible, or all possible NPE's are clearly documented in the source code itself.

Level 3: all classes checked; only JavaDoc annotation accepted

All classes in the project are checked. All new classes are automatically checked. JavaDoc annotations are accepted but in-line code comments indicating "don't check this line" are ignored.

This means that, for the entire package, client code knows that every possible NPE is specifically documented in JavaDoc. The API is either safe or clearly, externally documented.

This level is sufficient for most projects to be considered "clean."

Level 4: all classes checked; ignoring all annotation

At this level, NullSafe is instructed to ignore all source code and JavaDoc annotations when checking for NPE's. For client code that is not also at Level 3 compliance, this ensures the package will still not throw NPE's even if the client violates the documented contract. Note that source level annotation is still useful at this compliance level because it is good programming practice to document the expected behavior of each method.

This level is appropriate for libraries that are expected to be used in "unfriendly" environments, e.g. where NullSafe may not be in use.

Level 5: all target-code invocations are NPE-clean

At this level, not only is all code in the package checked, but all code invoked by the package is checked as well. This "target" code does not itself have to be at any particular compliance level — even 3rd-party code with no compliance and no source code will do — but your package must not make an invocation wherein the target code ends up throwing an exception.

If you have no control over the target code, and if the target code is fairly sloppy, it could be impossible to acheive Level 5 compliance.

Only at this level of compliance can you say that "No null-pointer exceptions will occur at all in this code base." It is difficult to achieve and unnecessary for many development organziations and projects.

Practical application of compliance levels

There is no reason not to acheive at least compliance Level 2. At this point you are providing the tool to your developers and in your automated build system, and at least some classes are being checked. Over time you might check more classes, especially in high-risk areas.

For any serious product, especially one with long expected lifetime or high reusability, it is worthwhile to achieve Level 3 compliance. This implies that an entire package, JAR, or project is fully-documented with regard to NPE errors; typically most of the possible NPE's will have been removed. It would be reasonable for customers to demand Level 3 compliance of software they purchase as one measure of product quality.

Level 4 compliance is not necessary for most internal project source code, but when a library will be "published" it becomes important. Once the code gets into the hands of another developer group who might not be at e.g. Level 2 or 3 compliance, achieving Level 4 ensures that your library is robust enough to behave properly even when abused. It would be reasonable for customers to demand Level 4 compliance for 3rd-party libraries they purchase as one measure of implementation quality.

Level 5 compliance can be reserved only for the most critical of libraries. Typically it can be acheived only with "low-level" libraries that depend on none or very few other libraries, where those other libraries are already mature, well-documented, and at least mostly null-safe. It is very difficult to acheve Level 5 compliance from the "top-down," that is starting with high-level libraries and working down to core libraries.

Tool Support for Compliance

NullSafe specifically supports these compliance levels. You can direct the tool to enforce a particular level on a set of code, either in an unattended build or inside Eclipse.

In addition, you can get a report on which code satisfies which compliance levels so you always know exactly where you stand.