Dan Sugalski <[EMAIL PROTECTED]> wrpote:
> Implementation should be capable of being yanked out and replaced
> with no notice, and things still work. It is, and should be,
> considered ephemeral. It's the least important thing to get right,
> since it can be fixed or completely replaced as we need to.
I'd also like to remind people that while documentation for designs +
interfaces go in PDDs, just as importantly PDD7 mandates documentation
for implementations (so poor schmucks trying to understand your code
can have a vague guess at what's going on). And I quote:
-----------
=item Developer files
For each source file (eg a F<foo.c> F<foo.h> pair), there should be an
accompanying developer file called F<foo.dev>. This text file contains
documentation on all the implementation decisions associated with the
source file. (Note that this is in contrast to PDDs, which describe
design decisions). 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.
Currently no particular format or structure is imposed on the developer
file, but it should have as a minimum the following sections:
=over 4
=item Overview
Explain the purpose of the source file.
=item Data structures and algorithms
Explain how it all works.
=item History
Record major changes to the file, eg "we moved from a linked list to a
hash table implementation for storing Foos, as it was found to be much
faster".
=item Notes
Anything that may be of interest to your successors, eg benchmarks of
differing hash algorithms, essays on how to do integer arithmetic.
=item References
Links to pages and books that may contain useful info relevant to the
stuff going on in the code - eg the book you stole the hash function
from.
---------
I'd also like to remind people of the following:
---------
=item Top-of-file comments
In addition to the copyright message and optional quote, each source
file must have a short comment at the top explaining the basic purpose
of the file, eg
/* pp_hot.c - like pp.c, this file contains functions that operate
* on the contents of the stack (pp == 'push & pop'), but in this
* case, frequently used ('hot') functions have been moved here
* from pp.c to (hopefully) improve CPU cache hit rates.
*/
---------
