> 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 https://github.com/ThreeTen/threeten/blob/master/src/main/java/javax/time/ZonedDateTime.java#L276 * @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) Stephen
