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

[Greg Falcon <veloso@...>]

On Mon, Feb 28, 2011 at 4:26 PM, Florian Weimer <fw@deneb.enyo.de> wrote:
> * 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?

Sometimes people don't read documentation.  But the use of member
names with spellings like "__foo" and "__has_foo" is itself a form of
documentation, strongly hinting that these represent internal state
and are to be left alone.  A user who finds the "__foo" member, and
uses that instead of "foo", deserves whatever problems this may cause
in the future.

Greg F