On Wed, Jul 17, 2002 at 03:56:39PM -0400, Andy Dougherty wrote:
> In practice, what we need is a supporting culture and infrastructure to
> make it most likely that useful documentation will get written and be
> in a place you can find it.
> Obviously, in practice, judgment will be needed for any particular bit
> of documentation. For example, take perl5's sv.c. There are certainly
> many implementation issues related to IV/UV/NV conversion that could be
> discussed in some sort of mini-essay (and there is such a mini-essay in
> sv.c). On the other hand, I think many of the extensive comments on
> those issues belong exactly where they are -- right next to the code in
> question.
I found I needed them there to preserve my sanity as I was attacking the
code. There is an important heath warning early on:
So as to not lose
precision as a side effect of conversion (which would lead to insanity
and the dragon(s) in t/op/numconvert.t getting very angry) the intent is
what hasn't been written (erk) is the user level documentation about what
goes on. I think Jarkko wants to release 5.8.0 rather soon, so I'd better
check perlnumber.pod is correct.
It was far more useful to me to have the relevant comments put near the
relevant bits of code. If they had been somewhere else I'd've been forever
switching between the two. And when someone else (ie me 2 months later)
came to change things, they were still all where I'd left them, in just the
right place. IIRC some other functions in perl5 got moved between source
files and the comments in them went along for the ride for free.
They are also useful as health warnings - there are comments in (say)
pp_hot.c warning about how not do addition, which anyone who is about to
change things will find hard to avoid reading. If they were elsewhere, then
someone confident may change the code without realising that someone else
already tried what they were about to do, and hit subtle pitfalls.
Nicholas Clark
--
Even better than the real thing: http://nms-cgi.sourceforge.net/
