Non-public public functions: Conventions for identifying?

[Antranig Basman]

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 - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://fluidproject.org/mailman/listinfo/fluid-work