I always tell people that a spec is not supposed to be a tutorial. I'm not
too fuss about having best-pratices on a spec.
Antonio
On Tue, Mar 6, 2012 at 21:37, reza_rahman_at_lycos.com
<reza_rahman_at_lycos.com>wrote:
> I think this is a pretty minor problem - probably best solved in more
> instruction-oriented material like the official Java EE tutorial :-).
>
> Mar 6, 2012 02:56:56 PM, users_at_javaee-spec.java.net wrote:
>
> ===========================================
>
> 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
> >>
> >
>
>
--
Antonio Goncalves
Software architect and Java Champion
Web site <http://www.antoniogoncalves.org> |
Twitter<http://twitter.com/agoncal>|
Blog <http://feeds.feedburner.com/AntonioGoncalves> |
LinkedIn<http://www.linkedin.com/in/agoncal>| Paris
JUG <http://www.parisjug.org>