Yes - I think the various reasons are not totally direct, but once they
are all laid out they argue for a small but consistent pressure for
these functions (public but not advertised as part of the framework) to
exist.
Firstly I wanted to refer back to some of our previous discussions on
this subject - here is a post I made in August in answer to a question
from Jen Bourey:
http://old.nabble.com/Re:-Code-style-guidelines-p29488737.html
I think I can make some of the same points that I made there a bit more
succinctly. Firstly I have to refer again to the Steve Yegge post that I
referenced there - which whilst humorous, makes a very serious point
about the practical consequences of the (let's call it) "Java stance"
towards code visibility. This stance basically says - "if you aren't
committed to maintaining this interface as stable for all time, don't
expose it to people at all". This sounds like a moral and safe principle
but actually in the long run it ends up being damaging.
I think the key point is that a core value of the Fluid community is an
appeal to multiple audiences. We are not simply designers, developers,
or users, but represent the interests of all of these communities
integrated harmoniously. We must certainly accept on the one hand that
the "traditional Java-stanced developer" is part of our audience - these
people want straightforwardly packaged functionality behind a
well-documented interface that has a clear public commitment to
stability from release to release. However, a significant (and I think
growing) part of our audience also consists of "experts and other
desperate people". I think it is every developer's experience when
starting to work on a new project, that in order to deliver a truly
excellent experience to their users, practically the very first feature
requested of them is one that the component set or framework that they
are using cannot immediately deliver.
This creates a familiar set of social forces - under pressure, the
developer will perhaps cut and paste parts of the framework code, or
perhaps even abandon the framework entirely. "people in a hurry" come in
two forms. The first group just wants to throw a pre-fabricated
component onto a page right now and get it working quickly. The second
group need to deliver something unexpected by the framework developers
and also get it working quickly. Given a choice between getting at least
*some* access to framework facilities, test cases and QA at the cost of
facing instability in the next framework release, this second group
would make the choice for instability every time. Especially if they are
the sort that only make framework upgrades infrequently and are
expecting significant costs at that time in any case.
All of this discussion would have been somewhat moot if there was no way
for users to configure in uses of these "broken-out semi-public
functions" or their own variants of them other than by calling them
directly from their own code. But with the IoC framework that is now
going in to the 1.3 release, each component in the framework will
increasingly expose transparent configuration that will let users
reconfigure its workflow with these variant implementations to a fairly
fine granularity.
Sorry - this wasn't succinct at all. Let me finish up with some bullet
points:
i) Fluid has a known and acknowledged audience of "expert and/or
desperate users" who would prefer to knowingly make the choice of
trading functionality for stability in the case they need to deliver new
user features in a hurry - that is, their development cycles are
significantly faster than Fluid can make a framework release.
ii) Hiding functions in private scopes creates the risk of cut'n'paste
code or even wholesale development of new approaches that can't be
easily contributed back to the framework in future.
iii) Writing core functions as public "utilities" forces us to think
more clearly about their contract and also constrains their range of
side-effects which improves the quality of the codebase in any case.
In terms of point iii) I noticed an interesting effect when working on a
Reorderer patch with Golam. The Reorderer code in question was written
at a very early stage in our "that-ist" understanding and was still
written to a Java-esque concept of hiding implementation functions
inside a large closure scope. Given that various variables were actually
visible inside the closure, one patch made the natural assumption that
this was intentional, and made a direct reference to the "that" that was
defined there. This now had the silent effect of increasing the coupling
of the implementation on its environment. Had the function been written
in the first place as a public standalone function, this risk during
maintenance would not have existed.
This leaves the somewhat difficult issue on the table though of how we
manage our communication as a community about what status different
public functions have. Some of them, for example, "fluid.reorderer" are
"gold-plated" and carry the full backing of our release-to-release
compatibility guarantees. Others of them, such the freshly created
"fluid.fetchResources.issueRequest" clearly do not - some of these
latter at first sight "look pretty odd" to a "Java stance" programmer
since they fail the initial test of "can I think of a reasonable reason
a user might actually want to configure or call this?". But all the
same, for the i)-iii) reasons above, I think the arguments in favour of
expressing it this way are reasonably sound.
In an IRC chat last week, we tabled the following possibilities for
communication:
i) Placing all such "non-advertised functions" in a special namespace
for example fluid.couldChange.fetchResources.issueRequest
ii) Applying a special comment syntax to every "non-advertised" public
function which would lead it to be identifiable as such
iii) Simply assuming by default that any such public function *without*
a doc-style comment was "non-advertised".
All of these options are problematic in a few ways - personally I think
we need some kind of combination of ii) and iii). I dislike i) because
it raises the risk of *gratuitous* incompatibility if at some point we
decide that the interface of a function is right after all and simply
want to change its status from "non-advertised" to "stable. It also adds
noise to almost the entire codebase. iii) is problematic sheerly because
it encourages laziness in commenting. It is also non-reversible - one
might imagine that a "non-advertised" function all the same receives
good documentation. ii) requires us to "get it right every time" in the
other direction.
So I propose some kind of combination of ii) and iii) - certainly every
function which doesn't receive good documentation should be considered
"non-advertised" - but I think it should be possible for us to mark even
well-documentated functions as either "unstable" (including "sneak
peak") or "non-advertised".
So - comments on this, and suggestions for what our conventions should be?
Cheers,
Antranig.
On 08/11/2010 11:32, Colin Clark wrote:
Hi Anastasia,
On 2010-11-08, at 10:26 AM, Cheetham, Anastasia wrote:
At the dev meeting last week, we discussed the fact that there are a number of
functions in the framework (and in some components) that are in the public
namespace but which are not really intended for use by the general public, and
which hence probably shouldn't have official documentation.
We discussed how we could identify these functions, so that the poor sod
writing the documentation doesn't waste time writing things that are best left
unsaid. Options included special naming conventions and an agreed-upon comment.
The general consensus of those at the dev meeting was a preference for an
agreed-upon comment (and NOT a special naming convention), but we wanted to
throw it out to the list before we implement it.
I missed the conversation last week, so apologies for asking a question that you no doubt covered
during the meeting. Can we identify the various reasons why any of these functions are public but
"not intended for the general public?" I imagine the rationale might include functions
that are "sneak peek" and subject to change in future releases, but are there any other
motivations for making them public but not documenting them?
Colin
---
Colin Clark
Technical Lead, Fluid Project
http://fluidproject.org
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
