I vote for pedantry, though not necessarily for every NPE.
I've had to port the JDK to a non-standard operating system. The docs are
frequently inadequate to answer detailed coding questions, so I end up reading
code to figure out what is supposed to happen. Even then, we sometimes don't
sort things out until we run the conformance tests.
The root cause, of course, is that the same spec serves as both user
documentation and implementation specification. It's inevitable that there
will be too much information for users and too little for implementers.
Tom Salter
------------------------------
Message: 3
Date: Mon, 26 Aug 2013 20:16:00 -0700
From: Mike Duigou <mike.dui...@oracle.com>
Subject: Re: RFR: 8021591 : (s) Additional explicit null checks
To: "core-libs-dev@openjdk.java.net Libs"
<core-libs-dev@openjdk.java.net>
Message-ID: <e6dd4778-9615-47c3-9cfe-7ab68593b...@oracle.com>
Content-Type: text/plain; charset=iso-8859-1
On Aug 26 2013, at 18:37 , Mike Duigou wrote:
>
> On Aug 19 2013, at 15:35 , Martin Buchholz wrote:
>
>> My feeling is that the JDK specs have been creeping in the direction of
>> excessive pedantry and doc lawyerism. I think it's overall a benefit of
>> Java that its documentation is more readable (at the cost of being a little
>> less precise) than the typical ISO spec.
>
> There is a definite tension here. We would like to keep the documentation and
> specification as readable as possible while still being sufficiently exacting
> so that behaviour of an API can be correctly predicted by a reader. It goes
> further than that though because Oracle employs an entire group of engineers
> who examine the JDK API javadocs looking for normative statements and then
> write tests to confirm that implementations conform to the API
> documentation/specification. The number and quality of tests they provide to
> ensure conformance has been steadily increasing (and accelerating). Is this a
> good thing? To me it seems so. When I hear that people encounter problems
> (other than performance) when switching among
> Vector<->ArrayList<->LinkedList<->CopyOnWriteArrayList or
> HashMap<->ConcurrentHashMap or TreeSet<->ConcurrentSkipListSet because of
> arbitrary corner case differences between implementations I become smy
Sorry, replying to my own message to finish an incomplete sentence.
...sympathetic to concerns that the JDK docs/specs are not specific enough.
Mike
