[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: Public APIs and documentation (was: Re: LuaJIT FFI __gc metamethod?)
- From: Greg Falcon <veloso@...>
- Date: Mon, 28 Feb 2011 16:37:02 -0500
On Mon, Feb 28, 2011 at 4:26 PM, Florian Weimer <firstname.lastname@example.org> 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.