specification for null handling in String, StringBuilder, etc.

Stephen Colebourne scolebourne at joda.org
Tue Jun 12 09:53:46 UTC 2012

> On 06/12/2012 07:40 AM, David Holmes wrote:
>> On 12/06/2012 7:59 AM, Jim Gish wrote:
>>> My personal feeling is that pre-conditions should be explicitly checked
>>> for and be spec'd.
>> This is very, very common in the core libraries. Rather than document
>> every single method where a null parameter triggers NPE they are often
>> covered (directly or indirectly) by blanket statements of the form "unless
>> otherwise stated ...".
>> I'm strongly of the opinion that people should be reading the complete
>> specification for any type they use, not just individual methods. So I don't
>> have a problem with not documenting this on each method - there are likely
>> to be far more significant misunderstandings of behaviour if you don't read
>> all the docs. But I understand others will see this from the other side.
>> Also note that the handling of unchecked exceptions by JavaDoc complicates
>> things because overriding implementations need to re-state that they throw
>> the NPE (or whatever it may be), using @inheritDoc, even if there is no
>> change from the superclass or interface specification of the method.

In JSR-310 and my other projects (OpenGamma, Joda-*) I explicitly
document null handling in a fairly non-invasive way, eg

* @param foo  the foo thing, not null
* @param bar the bar thing, null treated as a default bar
* @param baz the baz thing, may be null
* @return the foo-bar-baz result, not null
 public static FooBarBaz of(Foo foo, Bar bar, Baz baz) {

The rule I use is to add a clause to the end of the @param that
defines the null behaviour:
- ", not null" - this parameter does not accept null, null will throw
NPE or be undefined
- ", may be null" - this parameter does accept null
- ", null ..." - explain what null does

Similar explanations for @return:
- ", not null" - this method will never return null
- ", may be null" - this method may return null
- ", null ..." - explain when null returned, eg. ", null if not found"

This approach works well as a common pattern that developers can
understand without further reading or learning. It provides much more
data on null-handling, and in the location that the developer actually
wants it. I would love to see this approach more generally in the JDK
(and I suspect you might be able to get JUG hackathons to support
adding the text in to core Java classes)


More information about the core-libs-dev mailing list