Non-public public functions: Conventions for identifying?

[Colin Clark]

Hey Antranig,

Wow, quite an essay! I think that you actually summarize your point quite well with this snippet:

On 2010-11-08, at 5:28 PM, Antranig Basman wrote:

> 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.


So, we're taking a different approach in Infusion, where we ensure that everything useful that we create is also available for our users to adapt and extend. This actually speaks to another issue touched on by Eli earlier in the thread--exposing functionality for testing. In reality, we've found that if a function needs to be made public in order to be unit tested, it's usually a sign that our users may also need that functionality in order to be able to fully customize or adapt the component. Our instinct to make something private is usually a sign of poor factoring, rather than a need to legitimately encapsulate it.

This approach puts a burden on us to think deeply about the contract and API of all our public functions, and means we have to do a better job of communicating which functions are in progress or subject to change in future versions.

I think we already have a tool for how to handle this sort of thing: our component status levels. In particular, the "Sneak Peek" status gives users an opportunity to work with new features early, yet clearly identifies APIs that are likely to change in the future. Perhaps we want to augment this by labelling certain functions as sneak peek and not providing detailed documentation for them at all. I'd suggest that developers can simply label such functions in the source code like this: 

/** 
 * This function has a status of sneak peek and is subject to change. As a result, it is currently undocumented. 
 */

A comment like this should provide both our users and "the poor documentation sod," as Anastasia hilariously put it, with enough information to use bleeding-edge APIs wisely.

This brings us to Michelle's point: we need to compile a list of all the functions in Infusion 1.3 that are "sneak peek," as well as an accompanying list of all functions that we'd prefer to leave undocumented. Antranig, since you raised this issue originally, can you start us off by compiling a list of the functions you're aware of that are currently in this category?

Colin

---
Colin Clark
Technical Lead, Fluid Project
http://fluidproject.org