core-libs-dev Digest, Vol 76, Issue 112

[Salter, Thomas A]

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.duigou at oracle.com>
Subject: Re: RFR: 8021591 : (s) Additional explicit null checks
To: "core-libs-dev at openjdk.java.net Libs"
	<core-libs-dev at openjdk.java.net>
Message-ID: <E6DD4778-9615-47C3-9CFE-7AB68593B2C0 at 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