specification for null handling in String, StringBuilder, etc.

[Joe Darcy]

On 6/12/2012 6:04 AM, Alan Bateman wrote:
> On 12/06/2012 06:40, David Holmes wrote:
>>
>> 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 ...".
> Right, @throws NullPointerException can be considered clutter so it's 
> common to see a blanket statement in the class or package description. 
> In the case of String it already has:
>
>  * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a 
> constructor
>  * or method in this class will cause a {@link NullPointerException} 
> to be
>  * thrown.
>
> This was added via 4703640 a long time ago.
>
> Clearly a blanket statement like this doesn't make sense in all cases 
> as there will be APIs that define many methods that allow null.
>
> -Alan

Yes, in most cases lots of explicit "@throws NullPointerException if foo 
is null" is noise and should be avoided as a documentation pattern.  No 
one should be that surprised if a method nulls a NPE after having a null 
passed to it!

My preferred long-term solution here would be to use annotations to 
documentation the null-handling behavior, including class-level 
defaults, which would then allow tools to check null-handling of callers.

-Joe