users@javaee-spec.java.net

[javaee-spec users] Re: [jsr342-experts] Re: Code-Examples in the EE Spec

From: Bill Shannon <bill.shannon_at_oracle.com>
Date: Tue, 06 Mar 2012 11:56:35 -0800

I guess it depends on what you mean by "usage code".

There's a lot of sample code that does things like demonstrate how to do
a JNDI lookup, how to declare a field that will be injected, etc. Those
few lines of code aren't going to compile without a lot of other boilerplate
wrapped around them, which would obscure the point being illustrated.

Is that code "usage code" since it's showing you how to use those features?

I agree that if the example is showing you how to write an interceptor
(for example), that code probably ought to compile, plus or minus some
import statements. If it ignores error handling, that should be stated
explicitly.

In any event, I think we need to move this conversation from the abstract
to the concrete. Are there specific examples in specific specs that people
feel mislead developers?


Pete Muir wrote on 03/06/12 03:15:
> If sample *usage* code is included that won't compile or isn't complete, then shouldn't it just be removed.
>
> Ideally the spec would come with a "developers guide" or similar that showed how to actually use Java EE… This could be non-normative
>
> On 5 Mar 2012, at 21:35, Bill Shannon wrote:
>
>> Most of the code examples in specs are short excerpts intended to
>> illustrate a specific point. Rarely is that point how to do error
>> handling. I wouldn't thought this was obvious to people. :-(
>>
>> I certainly would not want to clutter up the examples with lots of
>> code irrelevant to the specific point.
>>
>> In most cases, the example code is obviously incomplete and won't
>> even come close to compiling as is. In cases where the example code
>> looks more like complete code (e.g, a complete class or method), it
>> would probably be good to include the usual disclaimer that "error
>> handling is not included".
>>
>> I'd like to believe this is just common sense advice to spec authors.
>> I'm not convinced there's a pervasive problem that needs to be dealt
>> with in all specs, and certainly not something that requires updating
>> the legal boilerplate in each spec.
>>
>> Markus Eisele wrote on 03/02/12 01:59:
>>> Hi all,
>>>
>>> I would like to start a short discussion about the use and quality of
>>> code-examples in EE 7 and the contained specs.
>>> The discussion I had with a couple of guys personally and via twitter
>>> ended up with Eberhard writing up his thoughts
>>> a bit more detailed here
>>> http://jandiandme.blogspot.com/2012/02/dangerous-code-example-in-ejb-31-spec.html
>>>
>>> To be honest, I have not seen this as a major issue. But looking
>>> around and asking my peers
>>> shows, that many of them are looking at the spec documents as the
>>> single point of truth if some container seems to behave weird.
>>>
>>> Beside the fact, that the spec documents should point out basic
>>> concepts and don't
>>> provide tutorial-like examples. I would like to see a general
>>> statement in place, which should also be included by all contained
>>> specs to
>>> explicitly state if code is pseudo code or incomplete to any other
>>> reason. Maybe this is something that could
>>> be added to to general DISCLAIMER OF WARRANTIES which already covers
>>> more general technical inaccuracies.
>>>
>>> Would love to get feedback about this and how your experiences in the
>>> field are.
>>>
>>> Thanks,
>>> - Markus
>>
>