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 [EMAIL PROTECTED]
with "unsubscribe freebsd-hackers" in the body of the message
