On Mon, May 01, 2006 at 02:11:21PM -0800, . . wrote: > I didn't insult Joe's Mom, but I don't agree that code is > documentation or vice versa. However, when I see either of you on > continuum, I plan to insult your mother. Good code is good documentation, for good code readers. Especially code that will change, as people seem to have difficulty updating the comments to reflect the code changes. It's no good at all to have a barely accurate or useful comment, possibly mis-describing the very accurate code. I find that unless the code is impossible to read (yuck), I'll read the code first, and only if I have questions, will I read the comments, to try to understand what in the heck the author was thinking when he wrote it. As to which of the three (more than one?) are lacking - I'll leave you to decide. :-) More seriously - The netrek code of 10+ years ago - when I actually wrote additional code for it client-side and server-side, was quite poor. Obviously the work of a few University grads in their spare time. I found it really hard to follow. The last time I looked at it - porting some of my changes back up to a more recent version, there was a great deal of improvement that I immediately noticed. I think this included ANSI-C, a re-written network/packet layer, and some nicer simplification in the daemon. I'd say this switched it from poor to average or better quality. I haven't looked recently to offer my condescending judgement for 2006... :-) Cheers, mark > > ----- Original Message ----- > > From: "Bob Tanner" <tanner at real-time.com> > > To: "Netrek Development Mailing List" <netrek-dev at us.netrek.org> > > Subject: Re: [netrek-dev] Netrek config utility source code > > Date: Mon, 1 May 2006 16:06:35 -0500 > > > > > > On Monday 01 May 2006 15:54, . . wrote: > > > Can you please explain what its purpose is, what this does in some more > > > detail, why anyone would want to use it, and how it works? Documentation > > > tends to be notoriously bad in Netrek -- almost like a sore thumb or a poke > > > in the eye with a sharp stick. > > > > I don't mean this to be flame-bait, but it will sound that way.... > > > > The documentation is the code. With that said, I agree the documentation is > > poor for Netrek, but if I had to pick, I'd rather have people writing code, > > then writing documentation. > > > > A smaller FOSS projects like netrek do not (usually) get the luxury of having > > both. > > > > My recommendation, see if you can get the author in irc and talk with him and > > write the documentation yourself. Why? Most devs, like myself, would write > > techno-babble documention which the end user wouldn't find all the useful > > anyways. :-) > > > > -- > > Bob Tanner <tanner at real-time.com> | Phone : (952)943-8700 > > http://www.real-time.com, Minnesota, Linux | Fax : (952)943-8500 > > Key fingerprint = AB15 0BDF BCDE 4369 5B42 1973 7CF1 A709 2CC1 B288 > > << 1.2.dat >> > > > > _______________________________________________ > > netrek-dev mailing list > > netrek-dev at us.netrek.org > > http://mailman.us.netrek.org/listinfo/netrek-dev > > > > > > -- > ___________________________________________________ > Play 100s of games for FREE! http://games.mail.com/ > > > _______________________________________________ > netrek-dev mailing list > netrek-dev at us.netrek.org > http://mailman.us.netrek.org/listinfo/netrek-dev > -- mark at mielke.cc / markm at ncf.ca / markm at nortel.com __________________________ . . _ ._ . . .__ . . ._. .__ . . . .__ | Neighbourhood Coder |\/| |_| |_| |/ |_ |\/| | |_ | |/ |_ | | | | | | \ | \ |__ . | | .|. |__ |__ | \ |__ | Ottawa, Ontario, Canada One ring to rule them all, one ring to find them, one ring to bring them all and in the darkness bind them... http://mark.mielke.cc/