On Sat, Jul 13, 2002 at 03:48:31PM +0100, Nicholas Clark wrote: > I was working somewhere where the chief technical architect, a very smart > guy, was far too busy doing stuff to write it down, and also didn't view it > as a priority as "I don't need to write it down, it's all in my head".
And once again, I'd like to remind people of the following section in PDD7: =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. =back -- But Pity stayed his hand. "It's a pity I've run out of bullets", he thought. - "Bored of the Rings"
