[arc-discuss] When should interfaces be private?

[Philip Brown]

Combination reply to multiple people's emails...

John Plocher wrote:
> Philip Brown wrote:
>>
>> I've had the long-standing impression, that, inside sun, "private 
>> interface" is pretty much synonymous with "dont have to document it".
> 
> 
> The inverse is certainly true:  If it isn't documented (man pages...),
> then it can't be a Committed or Uncomitted interface.  The level of
> expected documentation goes down for Volatile, and is (other than the
> keep off the grass notice) nonexistent for the "Not an Interface" ones.
> Private interfaces, by definition, do not have public documentation.
> 
> This is not to say that they are not documented - they are.  Just not
> on man pages and other end-user and end-developer facing things.
> 
> By definition, kernel developers ARE NOT the target audience for man
> page and end-consumer documentation.  

"man page and end-consumer documentation" is not what I'm talking about 
here,(and neither is anyone else, as far as I can tell)
We're talking about code-level "interfaces"? !
(yeah, there are manpages for "code", but I'm not talking about that either.)

 >Look in the ARC case logs for
 >that level of developer docs - that is why I put them out on OS.o.

Errr.. are you implying here, that even "private" interfaces, are actually 
documented in some degree, by these arc case logs you reference here?
That would be nice. If they all became publicly readable, and they were kept 
up to date, then it would make the rest of what I have to say, unneccessary...



Shawn Walker wrote:
> Engineers are not always the ones to write the
> documentation, and even when it is, not necessarily the same one that
> wrote it.

?? I'm not talking about Documentation, docs.sun.com style. I'm talking 
along the level of 'code comments' level of documentation.
That level of documentation, is of fundamental worth, even INSIDE sun.
In case some important bugfix or something comes up, and that developer is 
not available; sick. dead. or laid off. I hear that does occasionally happen 
at Sun!

You seemed to imply(in longer stuff I'm not quoting here) that documentation 
is a big "cost sinkhole" that is usually a poor ROI, so sun would be foolish 
to insist on documenting interfaces.

I'd say in reply, that the ROI would be from
1. improved ability for other engineers to take over when neccessary
2. showing the external developers, that sun is interested in actually 
spending person-hours in assisting "the community" to efficiently take full 
advantage of the code, rather than a "here's the code, now make it better 
for us, for free" attitude.



James Carlson wrote:
> As a consequence of assuming that nobody else is looking right at a
> function, you're free to rewrite it at will in any way you want,
> without having to consult with *anyone* or do any grep or cscope or
> google searches to locate other users.
> 
> If you had to do searches like that every time you changed a variable
> name, you'd never get anything done.

I agree there. What I'm suggesting, is only a "code comments" level of 
documentation, though.
And having an interface stability level of "volatile" or "uncommitted" or 
whatever, should mean exactly that they DONT HAVE TO "consult with anyone":
They just have to update the (developer-oriented) docs to reflect the new usage.

if someone starts using an interface with stability "volatile", they have no 
right to complain when and if it changes.
Yeah, they complain anyway. Tell them to deal with it, 'cause they knew the 
risks when they started using it :-)