Re: Public APIs and documentation

[Reuben Thomas <rrt@...>]

On 28 February 2011 21:34, Florian Weimer <fw@deneb.enyo.de> wrote:
> * Reuben Thomas:
>
>> On 28 February 2011 21:26, Florian Weimer <fw@deneb.enyo.de> wrote:
>>>
>>> This means that you need documentation which actually being read by
>>> developers.
>>
>> No, that just means that developers who don't read the documentation
>> don't get to complain when their code breaks.
>
> I'm not interested in shifting blame, I want to reduce the risk of
> breakage so that it becomes easy to extend a system (or rather, as
> easy as the application domain permits).

I said nothing about blame; I just don't think this is a problem that
is crying out for a technical solution.

Lua does not lend itself naturally to enforcing what is public; trying
to invent such a scheme is a good way to waste time, confuse
programmers used to more traditionally-written libraries, and merely
provide entertainment to those who insist on working around
restrictions.

In the mean time, a clearly documented public API remains a tried and
trusted solution to this problem. As noted elsewhere in the thread,
there are well-known conventions such as the use of identifiers
starting with underscores, and I can't say I've noticed nearly as many
problems with programmers working outside published APIs as with APIs
changing in bad ways, so unless you reckon you've solved the latter
problem, maybe the former is a bit of a distraction.

-- 
http://rrt.sc3d.org