[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Yellow pages

On several occasions I have started to collect all of the random code
files lying around here into an online libarary that, if it grows and
prospers, would eventually become the Yellow pages (or one version of
the yellow pages, anyway).  Then I get to thinking about what sort of
boilerplate to include in these files, and I end up putting the whole
thing off until I have time to think about this.  Well, here we go
again, and this time I'll ask for advice:

What information do we want to include with each program?  My initial
list is as follows:

A copyright notice or statement that the code is in the public domain.
Author's name.
Current maintainer, with mail and net address.
Description of the program (optional if there is a document).
Notes on any non-portable aspects of the code.
Known bugs and ideas for future extension.
Log of significant changes from one release to another.
Random comments.

Anything else?  Should this be in the same file as the code (in a big
initial comment), or a separate-but-related file?  Should we try to come
up with some syntax for making the fields easily identifiable by
machine, or is human-readability sufficient?

Probably we'll have two library directories, one for truly portable
stuff and another, much larger, for Perq-specific code (which still
might be of considerable use to people writing similar programs).

-- Scott