develooper Front page | perl.perl6.internals | Postings from July 2002

Re: [PATCH] .dev files.

Thread Previous | Thread Next
Andy Dougherty
July 17, 2002 12:56
Re: [PATCH] .dev files.
Message ID:
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

    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.
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

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
    Dept. of Physics
    Lafayette College, Easton PA 18042

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About