On 11/13/2012 11:24 PM, Pierre DELAAGE wrote:
If we would have to have deep understanding of the various codes we are
using everyday (I am myself a programmer, and openssl WCE contributor),
we would not have enough time to work, to produce anything.
Anyway understanding "what the code is SUPPOSED to do" is one thing, and
HOW it is doing it, another thing.
This is the basic difference between specifications and design...
There is also the fundamental rule that good docs indicate what is
allowed to silently change in new versions and what is generally not.
This is important for both library users (to avoid relying on things
that are not going to work in the next version) and for library writers
(to avoid changing things that users rely on).
Do you really need to understand the code of zlib to use it ?
the code of libpng to produce png ?
the code of c-lib (written in assembly !!!) to produce c code ?
(Aside: libc is written mostly in C with as few bits and pieces as
possible coded in assembly for each target CPU, I can say this having
seen the source code for at least GNU, uclinux, Microsoft and Borland
implementations of libc).
So, this kind of argument is just pretending sarcasm.
Maybe the doc could be improved by a kind of wiki system ?
Where people having found useful answers in the distribution list could
push back some useful info.
This is just a suggestion.
Nah, wiki documentation tends to get completely out of sync with reality
and itself, I have seen that failure in other OSS projects.
Once written, documentation needs to be in sync with the code, just as
header files and test cases do.
Le 13/11/2012 23:13, Ted Byers a écrit :
On Tue, Nov 13, 2012 at 4:38 PM, alan buxey <a.l.m.bu...@lboro.ac.uk
<mailto:a.l.m.bu...@lboro.ac.uk>> wrote:
> Nonsense. No-one knows better how the code ought to be
working than the
> folk who developed it. I begin with the assumption that all
my coders are
i'd cite the cathedral and the bazaar ...or the 'many eyes make
all bugs shallow'
views - if you are given the API and the documents, you use the
code without seeing
what its doing. by looking at each library you can see what it
does and how it does it
but most importantly, you can see the bugs/issues/problems.
You neglect context. My junior staff generally don't see the library
implementations, even when we own the code. To ask them to study that
code pushes them way too far much too fast. I want junior staff to
develop at a reasonable pace; but at their own pace. I will not
assign them tasks that they haven't a hope of completing in a
reasonable timeframe. That is just plain cruel! It is madness to
expect a junior coder to have all the expertise of a senior software
engineer. To do so is a recipe for disaster, and for rapid burnout of
your junior staff. Your cathedral and bazaar metaphore therefore does
not apply in most cases.
Your metaphore only applies in the case of senior programmers
interacting with other senior programmers. And, when it comes to
security, you want as many senior programmers' eyes on the code as is
possible. And I would be concerned about using a library that my
senior staff have trouble figuring out. But even this does not excuse
the senior programmers responsible for developing the code from
documenting it. There is no-one better to do it, especially if they
put themselves in the place of the junior programmers they are
responsible for training.
with the closed source proprietary software you expect to get 100%
perfect docs because
you cannot see the source code - you are told how it works and
what to feed it. thats that.
That's just plain wishful thinking! The perfect product does not
exist, closed source or otherwise! We know software engineers are
human, and thus error is always certain in any document. It is,
though, to be expected that closed source software and its
documentation goes through a QU process to ensure that error is at a
minimum, and also that their support staff are sufficiently senior
that when a user encounters a problem, they are competent enough to
jointly test the nature of each complaint and correctly distinguish
between a bug in their own product and user error. In a product that
is acceptable for production use, from an acceptable supplier, it is
never a case of "that's that". Failure on either count above
guarantees that the library in question will not be used, at least in
any product I am responsible for.
yes, one can complain until you are blue abotu documentation - and
a few comments in this
thread have certainly alerted me to some of OpenSSLs other issues
- enough perhaps to look
at GNUTLS or some alternative....'ReallyOpenSSL' anyone? ;-)
It is always a question of examining whichof the available
products/libraries to use, vs writing your own code. In every such
case, it is a question of having (only) your senior staff invest a bit
of time to evaluate the options. This includes applying tests to
determine the adequacy and reliability, and limit s of application, of
the product in question.
I will not waste time on complaining about documentation for one
library or another. Instead, I will examine the product, including
its documentation. I will then make a judgement as to whether or not
it will be used, and by which of my staff. We might even decide to
use multiple compeeting products for different tasks, perhaps with our
own 'abstraction layer' to ensure that what we have our junior people
coding to is of sufficient quality and that we do not get hurt by
deficiencies in each of the products we're using. I set the coding
standard for me staff, as well as the criteria that must be met by any
library, or other tool, we will use; along with any conditions for
their use. And nne of that is static. Some of the senior staff are
responsible for reviewing available libraries, with a view toward
adding or removing products from teh mix, based on deficiencies and
improvements that appear in each as they develop.
Enjoy
Jakob
--
Jakob Bohm, CIO, Partner, WiseMo A/S. http://www.wisemo.com
Transformervej 29, 2730 Herlev, Denmark. Direct +45 31 13 16 10
This public discussion message is non-binding and may contain errors.
WiseMo - Remote Service Management for PCs, Phones and Embedded
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users@openssl.org
Automated List Manager majord...@openssl.org
