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

[Axel Kittenberger <axkibe@...>]

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

I'd discourage extensive usage of leading underscores as
distinguishing marker. First it just makes the core just harder to
read. Second In many languages (lua included!) leading underscores
serve for language specific identifiers. This includes the
metamethods. I'm not fond of the leading underscores the lua
metatables expose to the user, but hardly have alternative suggestion.
Anyway, if you heavily use leading underscore for your codes internal,
to mark the differences between your public API and private API, this
makes them superfluous to distinguish language design extensions.
Maybe in the next lua version __something just suddenly means
something special for the lua interpreter? Third, your barrier between
public and internal is in larger projects not the only barrier, you
have libraries, modules which also have their barriers, now if
everybody flings around with a lot __underscores, it just isn't a
barrier anymore. Eventually I suspect that some people just make a lot
of __leading __underscores, because it makes the code "look cool",
this excludes of course you, the reader :) Especially in C times,
__underscores marked compiler or c-library internal hacks that albeit
introducing incompatibilities where often some clever optimizations.
Now if you also use a lot of __underscores doesnt automatically make
your code clever, but it looks more.