On Wed, 17 Jul 2002, John Porter wrote:
> As someone else has already said, a better place
> for the .dev information might be inside the .c
> file itself.
> I for one find the separation unnatural,
> uncustomary, and de-sync-prone.
> Frankly I just don't see what it buys us.
Obviously, in principle, documentation could go anywhere, assuming it
actually gets written.
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.
I think the purpose of the .dev files, as laid out in
docs/pdds/pdd07_codinstd.pod, is a reasonable one. Here's an edited
excerpt:
This text file contains documentation on all the implementation
decisions associated with the source file. This is the place for
mini-essays on how to avoid overflows in unsigned arithmetic, or on
the pros and cons of differing hash algorithms, and why the current
one was chosen, and how it works.
In principle, someone coming to a particular source file for the
first time should be able to read the F<.dev> file and gain an
immediate overview of what the source file is for, the algorithms
it implements, etc.
Suppose, for example, that the author of hash.c chooses hashing
algorithm B over algorithm A. At the top of hash.c, it would be a bit
odd to see a mini-essay describing A since it's never used. On the
other hand, having done all the work to decide B is better than A for
parrot, it would be useful to record that decision somewhere. hash.dev
is one sensible place for 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.
Obviously, in practice, judgment will be needed for any particular bit
of documentation. If many of the .dev files end up very brief because
there were no significant implementation issues to address, or because
everything is clear from the .c file, or then so be it. I suspect
there will be at least a few files that could benefit from some
mini-essay somewhere describing the implementation issues.
--
Andy Dougherty [EMAIL PROTECTED]
Dept. of Physics
Lafayette College, Easton PA 18042
