[openssl-dev] [openssl.org #4343] master: EC_KEY_priv2buf (): check parameter sanity

[Viktor Dukhovni]

On Fri, Feb 26, 2016 at 12:50:24PM -0500, Jeffrey Walton wrote:

> > Nonsense.  Source code is not API documentation, it is an
> > implementation, not an interface contract.
> 
> I'm not sure I'd consider it nonsense.

Comments in source code are not documentation, they explain the
internals of the implementation, not the contract.  Users of a
library need to depend on documented semantics, not implementation
artefacts.

> Studying source code on occasion is simply par for the course when
> working with open source libraries.

Here, by "open source" you mean poorly maintained.  I'd like OpenSSL
to leave that legacy behind.  Not all open source software is poorly
maintained and under-documented.

> In my naiveness, if you want something to be private, then you don't
> expose it to the outside world.

That too, but not documenting an interface should be sufficient to
dissuade users from relying on it.  Sadly, important parts of
OpenSSL are not yet documented, and I am proposing we become more
aggressive about fixing that.

One way forward is to ensure that changes must come with documentation,
created if missing, updated if the interface is extended, or changed
incompatibly.

> It also seems like if a function leaks into a public header, then you
> state that its private and it should not be called. What's the
> aversion to a clearly and succinctly stating something?

All I'm saying is that documentation is not optional.  Neither source
code nor header files are documentation.

> > Bug fixes to undocumented functions will be buggy, and the
> > documentation will never happen.  We need to improve code quality,
> > a good part of that is having documentation.
> 
> If the code is
> buggy, then it should be fixed or removed. There's no middle ground.

It must be fixed *and* documented.  Over and out.

-- 
	Viktor.