Date: Sun, 27 Jun 1999 15:53:52 +0100 From: Karl Pielorz <kpielorz@tdx.co.uk> To: Greg Lehey <grog@lemis.com> Cc: Constantine Shkolny <stan@osgroup.com>, "hackers@FreeBSD.ORG" <hackers@FreeBSD.ORG> Subject: Re: All this and documentation too? (was: Microsoft performance (was: All this and documentation too? (was: cvs commit: src/sys/isa sio.c))) Message-ID: <37763B00.15894ADD@tdx.co.uk> References: <01BEBFCB.F95F6F00.stan@osgroup.com> <19990627093124.N427@freebie.lemis.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Greg Lehey wrote: > > I've come to understanding that lack of documentation is probably one of > > the factors that keep the system healthy, because it keeps the unskilled > > people away. I don't know whether it's true but I read in books that > > reading code is one of the methods to learn programming. Since FreeBSD > > does ship with source code, docs are not necessary. NT ships with poorly > > written docs instead, and, that is what kills it all the time, despite of > > its perfect design that I really like. People write NT drivers without > > full understanding what is going on, so they destabilize the system. > > I can't agree with this theory. Lack of documentation just moves the > degree of skill needed to, for example, write device drivers. > Document less well and your average device driver writer will write a > worse driver, with or without source code access. Source code access > helps too, of course. Coming from someone who's struggled to write a device driver, and then had to move the driver from 2.X, through to 3.X to 4.X (it's currently languishing somewhere along the line of 3.X) - I would wholely agree with Greg. Documentation is _very important_ even more so in a rapidly moving system... Having access to the source code is one thing, but 'c' was not designed for documentation, it was designed to program in... Looking at the current array of drivers in -current you get the idea everyones done it 'slightly differently', and no one comments their code enough to make it 'self documenting', nor has anyone singled out any of the vast array of drivers and said "this is a good example if your writing ISA drivers", or "this is a good one to go from if your writing PCI". Just my annoyed $0.02's worth! :) -Kp To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?37763B00.15894ADD>