Re: Public APIs and documentation

[Mike Pall <mikelu-1102@...>]

Florian Weimer wrote:
> 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.

Enforcement is the job of the project manager. This may be
assisted by documentation and tools, of course.

> There is probably no correct answer for all development team,
> but perhaps some of you could share your experiences in this
> area.

Sadly, there's a widespread belief in the industry, that
technically enforced encapsulation guarantees anything about the
quality of the resulting product. This is completely missing the
point and probably another instance of Stockholm syndrome.

We all know that software development does not scale well. I've
seen some unbelievably bad code come out from 'enterprise'
development, even though they had plenty of processes and
restrictions in place. Rest assured: no technical solution
whatsoever would have helped them to prevent this.

But this is getting off-topic for the Lua mailing list. Sorry.

--Mike