Re: [wtp-dev] proposed package naming convention to distinguish 'work in

[David M Williams <david_williams@xxxxxxxxxx>]

Well ... before my name get's associated
with the term "internal.api" ... let me make clear *that* is
not what I meant. I thought that was proposed as a joke, though I like's
Craig joke of "internal.api.XXX" best, since that captures the
true double meaning of "todo task" and "poison" :)
Both true for the types of "APIs" we're talking about. 

My suggestion would be more along the
lines of what Michael Elder suggested ... to go ahead and start a "proposed
APIs for future releases" section of development resources, and teams
can name current "near APIs" with meaningful names like "internal.uriresolver"
or "internal.navigator", and easily relate those to the "uriresolver
proposal" or "navigator proposal" ... just to pick a few
random hypothetical examples :) Of course this should never detract from
the hard work we still have to do for release 1! -- which is, I think,
why Jeem and I advocate the more conservative approach.  Besides the
"API First" mantra, another Jeem API-ad-slogan comes to mind
... "no API before its time" ... and my personal favorite Occam's
Razor litany, "if in doubt, leave it out". 

If further discussion is to continue,
it might help if Craig or others interested in the "multiple layers"
approach could give some specific examples (of near API and reasons why
not API) -- maybe I'm missing something in the generalities. 

David

Chris Brealey <cbrealey@xxxxxxxxxx>
Sent by: wtp-dev-admin@xxxxxxxxxxx

03/08/2005 07:59 PM

Please respond to
wtp-dev

To	wtp-dev@xxxxxxxxxxx
cc
Subject	Re: [wtp-dev] proposed package naming convention to distinguish 'work in progress' API

+1 to David's comments and Craig's original suggestion - if they can co-exist.

Speaking for a component that I believe will have much less public API
in WTP 1.0 than I would like, I think there is value in a package name
that identifies services which are internal but likely to morph - possibly
in a big way - into public and permanent API down the road. Replacing "internal"
by "provisional" might be misconstrued by clients. Instead, how
about a convention of "internal.api"? The "internal"
would keep it clear that clients who need stability should steer well clear
(as Jim says), while the "api" would provide, at a glance, a
hint to clients that these particular internal classes/interfaces represent
an intention to design replacement public API in a future release.

My main concern driving the above is I am not comfortable that we will
have sufficient customer review of the proposed API we will try cooking
up over the next roughly six weeks. I neither want to declare public API
without sufficient review, nor completely discourage customers from identifying,
using and assessing internal classes/interfaces that we wish to promote
to public API. In summary, "internal.api" really means "candidate",
and would invite customers with a need (or just a healthy sense of adventure)
to use it, influence its evolution to public status in a later release,
and yet remain acutely aware that it's internal and likely to change.

That's my two cents' worth, anyways. 

Cheers - CB.

Chris Brealey
Rational Studio Java Web Services, IBM Canada Ltd.
D3-275, D3/ENX/8200/MKM, 8200 Warden Avenue, Markham, Ontario, Canada,
L6G 1C7
cbrealey@xxxxxxxxxx, 905.413.6038, tieline:969.6038, fax:905.413.4920