Public APIs and documentation (was: Re: LuaJIT FFI __gc metamethod?)

[Florian Weimer <fw@...>]

* Mike Pall:

> Josh Haberman wrote:
>> But then I have to trust users not to touch the real
>> members obj.__foo and obj.__has_foo whereas with a userdata
>> I can make them mostly inaccessible.
>
> Well, why do you mistrust the users of your code? Document the
> public API and deny support if they use any undocumented parts.
> If you can't trust your fellow developers, then none of this
> protected/public nonsense will help, anyway.

This means that you need documentation which actually being read by
developers.  Is this feasible in practice, outside high-integrity
systems and other niches?

Maybe I'm a bit pessimistic, but I think it's very difficult to
enforce a distinction between a public API and private internals
merely through documentation.  I'm working with a moderately large
codebase written in a dynamic language (not Lua), and it is often hard
to predict if changes are safe across the whole system.  There is
documentation, but you cannot really be sure that no one is peeking or
poking at the internals (neither you can be with languages which
nominally offer a public/private distinction---we carefully update
private fields in certain Java classes from the outside to install bug
fixes *sigh*).

I would have thought that with Lua, you'd go ahead and use proxies for
data structures which are expected to be moving targets, to make it
rather difficult to access the private parts.  There is probably no
correct answer for all development team, but perhaps some of you could
share your experiences in this area.