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
>