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