specification for null handling in String, StringBuilder, etc. (original) (raw)

Joe Darcy joe.darcy at oracle.com
Tue Jun 12 15:33:38 UTC 2012


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: *

Unless otherwise noted, passing a null 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



More information about the core-libs-dev mailing list