--- James Cameron <quozl at us.netrek.org> wrote:
> It is quite a simple code base.  There is very little

Simple for you :) 

> need for any 
> documentation.  There are only a few C source files, and

I counted well over 200,000 lines of code. That is a 'few'?

> tools to 
> track the calling order are far more reliable than any
> external 
> documentation.  

What are these tools?

>Tracing execution manually is quite
> straightforward,
> though people with short term memory problems may need to
> use pen and
> paper for some of it.

That would be me :)

> We have already seen the dangers of documentation that is
> maintained 
> separate from the source file (aka the trimscores issue),
> and so 
> documentation within source is my preference.

Ok. Many (most?) files don't even have a comment header at
the top saying at the very least the purpose of the code in
there and short documentation of the functions. Something
such as:

// FILE: intarray.h
// WRITTEN BY: Michael Main(main at colorado.edu), Aug 26,
// PROVIDES: A toolkit of four functions for manipulting
integer arrays.
// FUNCTIONS in the intarry toolkit:
//   int index_of_minimum(const int array[], int size)
//     Precondition: size must be greater than zero.  It is
the number of
//     elements in array (so array goes from [0] to
//     Postcondition: The value returned is the index of
the smallest entry
//     in array[0] through array[size-1].  If several
entries have an equally
//     small value, then the index of the earliest entry is

> While improving documentation may well reduce the time
> that new
> developers take to get up to speed, I'd much rather have
> those
> developers work on client packaging and ease of use.  We
> just don't need
> new server features right now.  That doesn't mean I won't
> accept them,
> just that if I'm to get enthusiastic about something then
> it should be
> about things that will increase the player base.



Do you Yahoo!?
Faith Hill - Exclusive Performances, Videos & More